Pre-amble
I write a column for Red Hat Magazine. The column's called How to Write Really Good Documentation, although we won't know how immodest that title is until a few more columns appear. (FWIW, it isn't my title. When I proposed the column, I called it word matters (or words matter). I still like that title, and it's the folder name I use on my own machine for column-related files.)
Obligatory disclosure: I also work for Red Hat as a technical writer. As well, Red Hat Magazine is entirely funded by Red Hat.
My 2nd column for the magazine is called Four rules and an axiom. I, of course, recommend you rush off and read it now, if only because the words below won't make as much sense otherwise.
When you get to the comments section of the article, you'll see the first comment is also by me. It was submitted along with the article, to be posted as a comment. So, no surprises for anyone there.
Except, the copy I submitted was bursting with links. Fourteen, to be precise. And that caused Red Hat Magazine's comment spam filters to throw a fit.
The comment eventually went public, but it did so sans-links. And that's a bit frustrating for yours truly, because the links are part of the copy.
So, I'm posting the comment here, complete with links (and title tags).
Post Proper
The Computer Book Publishing List, a mailing list run by StudioB, had a thread on the question of technical writing vs book authoring in late-January 2007.
The thread was started by a question from Stuart Mudie: What makes book authors different from tech writers, in your view?
Dee-Ann Le Blanc defined the difference thus:
Most tech writers are not Subject Matter Experts. They interview the SMEs. Book authors have to be the SMEs more often than not.
Judyth Mermelstein got almost adversarial, suggesting
In the computer world, technical writers work for the Company that pays them. They turn information the company provides into documentation that makes the product look good to the customer so it will sell well. That can mean using impenetrable jargon the boss is proud of inventing or omitting to mention known bugs and whatnot.
Ideally, technical authors work for their Readers. They thoroughly examine both the product and its documentation. Then they try to provide all the information the reader really needs, in a better (more accurate, more readable, more logically organized or whatever) [form] than the documentation the manufacturer's technical writer(s) produced.
In the first case, you're working for the industry; in the second, for the public good and your own satisfaction.
Margy Levine Young takes a similar, if less polemic, view to Mermelstein:
Computer book authors write from the point of view of the user: what do you want to do, and how do you do it. Manuals usually write from the point of view of the program: here's what it can do, here are the menus, here are the options. It's a big difference.
Laura Lemay comes in on the tech writer's side, noting
There has been a push for "user-centered design" of documentation for at least 25 years. Anyone in corporate technical writing who is still writing program-centered docs is not paying attention to industry practice.
(It's worth noting some of Lemay's career history here. According to her FAQ she 'gave up writing computer books' and is now a 'contract technical writer in Silicon Valley [who writes] programmer documentation, mainly.')
Back to her comments in defence of tech writers, she closes her post to the CBP list with the almost standard refrain regarding companies and the low priority documentation has:
a lot of documentation in companies is still written by whoever the company can scrape up at the last minute to write it, eg, the lowest status engineer, QA, an intern, the receptionist...
In a 2nd, longer, post, Lemay expands on Mermelstein's point, without getting as adversarial:
[I]n documentation you represent the company and the company's point of view. Documentation in some ways is a sales tool of the product. You're expected to ignore or gloss over possible problems in the product you're writing about, or advantages of the competition. In computer books you can be more honest, more broad, and more critical.
In documentation, you have to document all parts of the product evenly, even the stupid features that no one uses (every product has some). In computer books, you can focus on the real features that people actually use most often.
She also re-states her point regarding the importance, or lack thereof, accorded documentation by many companies as well as explaining why computer books aren't seen in the same light:
Many corporations consider documentation a necessarily evil but don't give it much attention or respect. As a tech writer you may be brought onto a product too late to do a good job and then get no access to either the product or to anyone who will explain how the product works because they're too busy to waste their time with you. This goes a long way toward explaining why a lot of documentation sucks so badly. As a computer book author the book is the product and is thus the center of attention.
All well and good, but what has this to do with the four rules and an axiom column?
Quite a lot. The CBP discussion thread provides an alternative way of expressing the underlying goal of the rules: to the extent it is practical to make documentation more like a computer book, make it so.
There are constraints, of course. Lemay's point about documenting 'all parts of the product' occasionally have legal force behind them.
And the authorial voice several contributors are fond of isn't especially welcome in formal documentation.
That said, this doesn't mean there should be no voice in good documentation. Like news reports, documentation is the better for being mostly short, declarative sentences. Using nouns and verbs in preference to adjectives and adverbs makes for clearer instructional prose. And avoiding the passive voice makes for easier to comprehend text.
In short, the so-called 'transparent voice' of the good news reporter, praised because they don't seem to be there at all, is the technical writer's preferred voice.
But, voice aside, making documentation more like a computer book is still a useful way of working towards the same goal as the four rules, especially in light of Lemay's last point.
How much better would the average user manual be if it was considered a product in its own right?