Front, Kernel, Security, Distributions, Development. See your byline here on LWN.net.

Create an account

Subscribe to LWN

LWN.net Weekly Edition for February 9, 2012

XBMC 11 "Eden"

LWN.net Weekly Edition for February 2, 2012

A tempest in a toybox

LWN.net Weekly Edition for January 26, 2012

Printable page

Weekly edition	Kernel	Security	Distributions	Contact Us	Search
Archives	Calendar	Subscribe	Write for LWN	LWN.net FAQ	Sponsors

Technical Writing Using OpenOffice.org Writer (O'ReillyNet)

Posted Aug 26, 2004 2:34 UTC (Thu) by horen (subscriber, #2514)
Parent article: Technical Writing Using OpenOffice.org Writer (O'ReillyNet)

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).

(Log in to post comments)

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 (guest, #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 (guest, #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 (guest, #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 (guest, #3554) [Link]

I do not agree at all.

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 (guest, #3554) [Link]

Oh, and I don't think OpenOffice can touch an ascii editor and scribus
for 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