Weekly Edition
Return to the Press pageSponsored link
Serve your customers, not your servers, with VERIO Linux VPS. Full-access test-drive here.
| Weekly edition | Kernel | Security | Distributions | Search |
| Archives | Calendar | Subscribe | Write for LWN | LWN.net FAQ |
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
(Log in to post comments)
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 0:45 UTC (Thu) by melevittfl (guest, #5409) [Link]
In my personal life, I'm a big promoter of open source software. However, as a professional technical author, I have to say that none of the open source offerings come close to providing the features of FrameMaker.
I use OpenOffice as a substitute for Word. It's very good as a Word replacement. But, it's not a replacement for FrameMaker. Although, if you're using Word to do technical writing, I could see the appeal.
So, I guess if you can't afford FrameMaker, then you should consider OpenOffice. But, if you can afford the software and the training, FrameMaker is the real goal for technical books.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 1:11 UTC (Thu) by dang (subscriber, #310) [Link]
If you need FrameMaker type features, then the better open source choice would be scribus.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 21:15 UTC (Thu) by melevittfl (guest, #5409) [Link]
Hmm. I had a look at Scribus. While a very good package, it seems to be more aimed at QuarkXpress or Pagemaker users.
It's certainly nowhere near the functionality of FrameMaker.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 2:34 UTC (Thu) by horen (subscriber, #2514) [Link]
If you're using any DTP software, then you're not a technical writer; you're a production/graphics person. Technical writers use vi or other ASCII editor, concentrate on content, and leave the visual layout to professionals trained in that discipline.
Technical writing is about content, and that means spending hours with the design engineers and the software, not with Word, WordPefect, Writer, Scribus, FrameMaker, or Interleaf. REAL technical documentation is supplied in HTML-formatted files.
Yes, I'm an opinionated SOB; but I spent 1974-1988 working as a technical writer, writing about weapons systems, methods-and-procedures, vocational training courses, and more -- all without DTP software (since 1988 I've been a Unix sysadmin, and would never go back).
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 6:16 UTC (Thu) by crankysysadmin (guest, #19449) [Link]
I wish you were right, but unfortunately, at least at the companies I've worked at since 1996, the technical writers do frequently do it all, including DTP, and from the talk I hear among the colleagues, it's definitely not uncommon for every tech writer to have a copy of FrameMaker on their Windows workstation *wince*. vi is something people speak of in hushed tones.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 7:49 UTC (Thu) by Arker (guest, #14205) [Link]
I worked for awhile as a technical writer myself, and I could go on for hours about what was wrong with that company and that job. But yes, I did not just the writing but the layout and so forth. I used Xerox/Ventura Publisher and Word for the final products, as it was required, but I also did most of the actual writing in an old DOS text editor, then sucked the text in and formatted it. This is a much more efficient system I think, so I find myself heartily agreeing with the gist of what the grandparent post said.
An odd thing with Publisher was that it would sometimes inexplicably mess up certain things, text would disappear or refuse to layout properly. This was a well known frustration to the other writers in the office. I took a look at the data and found that it stored the text and markup information in a flat text file, which was relatively easy to figure out, so I often wound up fixing these problems for myself and others in the office with my trusty text editor. Kill publisher, open the markup file in text editor, clean up the markup, eliminating the cruft that had accumulated, save and reopen Publisher and voila, problem solved.
Don't even get me started on Word. Hate it. Not a big fan of OO Write either frankly, the whole 'word processor' paradigm is fatally flawed I say, but Word is the worst of the lot.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 8:31 UTC (Thu) by djabsolut (guest, #12799) [Link]
Let's not forget about "LaTeX", which is included with all decent linux distros. Here you concentrate on the content (in a relatively simple markup language), and then tweak the result later. Labels for sections, equations and references are all taken care of in a nice framework.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 27, 2004 19:26 UTC (Fri) by cpm (subscriber, #3554) [Link]
"Not a big fan of OO Write either frankly, the whole 'word processor' paradigm is fatally flawed I say,"
I like OO, use it for a lot of stuff, that said, I wholly and completely agree about the so-called word processor. It's a very very bad idea, and it
has just been getting worse with no end in sight.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 11:38 UTC (Thu) by uriel (guest, #20754) [Link]
The best technical writer uses the best typesetting tool: troff(1)The same tool used by the best documentation system: man(1)
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 16:49 UTC (Thu) by jwb (subscriber, #15467) [Link]
Let's not pick favorites, but Knuth uses neither FrameMaker nor OpenOffice.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 17:28 UTC (Thu) by uriel (guest, #20754) [Link]
Very true, TeX is not bad, specially for math centered work, but troff is still my favorite.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 26, 2004 17:23 UTC (Thu) by AJWM (subscriber, #15888) [Link]
Way back when (20+ years ago) I was doing a fair bit of technical writing. On a rather lame computer for the task (a CDC Cyber, with (then) it's strange 6/12-bit character set. I ended up writing a [gtn]roff-like processor, actually modelled more on {IBM, Waterloo} Script. Portable, written in Pascal (internally it used a defined character type essentially ASCII, translated on input and output). It was used by a few other Cyber sites, and for years I used it on DOS (compiled with TurboPascal) and Unix for my own writing. Called it "formal".
I was certainly inspired by the roff series (including DEC's old runoff), but liked the more regular command set of Script. (If anyone cares, the source can be had from http://www.ajwm.net/amayer/software/readme-fml.html) It was used to produce quite a few manuals, papers and other documents at Concordia Uni. and other places back in the day.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 27, 2004 19:21 UTC (Fri) by cpm (subscriber, #3554) [Link]
I do not agree at all.
Being able to outline the page, insert the graphics/illustrations/figures and
captions, see how the footnotes are going to land have a HUGE
impact on being able to generate a treatment that the
intended audience is going to actually READ.
Big problem with so-called Technical Writing, is that it is
often put together for those who HAVE to read it, rather
than inticing others to read it for personal edification, etc.
I hardly ever read included docs beyond any notes about
building and config switches, and go straight to the store
for the O'Reilly manual. The books that come with prop
software, go right in a ziplock, and go into the file
cabinet with the distro media.
Why? Because I find the overall presentation of the O'Reilly
books to be just my cup-o-tea. I can read them on the couch
and not feel like I /have/ to read it. It's almost like
reading for fun.
For this purpose, I much prefer a very basic text editor/spell
checker, like Abiword, or something, sometimes emacs for
the content generation, and Scribus for the doc prep.
I flip between the screens, see what is lacking, fix it, move
on to the next section.
I live it, I love it.
--
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 27, 2004 19:22 UTC (Fri) by cpm (subscriber, #3554) [Link]
Oh, and I don't think OpenOffice can touch an ascii editor and scribusfor this task.
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Sep 9, 2004 1:58 UTC (Thu) by roelofs (subscriber, #2599) [Link]
Being able to outline the page, insert the graphics/illustrations/figures and captions, see how the footnotes are going to land have a HUGE impact on being able to generate a treatment that the intended audience is going to actually READ. [...] I hardly ever read included docs beyond any notes about building and config switches, and go straight to the store for the O'Reilly manual.Hmmmm...I wrote my O'Reilly manual in troff using vi. Granted, the final layout and so forth was done by a real editor, but the "technical" and "writing" parts of the technical writing happened without any particular concern for page outlines, footnotes, locations of figures, and whatnot.
But maybe that's just me. [ObBayLink reference]
Greg
Technical Writing Using OpenOffice.org Writer (O'ReillyNet)
Posted Aug 27, 2004 14:47 UTC (Fri) by david_mentre (guest, #19805) [Link]
For technical writing of scientific documents, I would recommend TeXmacs (http://texmacs.org). It tries to reimport the best of TeX, but in a visual editor. It is not perfect neither, but had improved a lot in recent time-frame.