2007 02 03 at 23:15
· Another in a series of distractions by Brian Forte

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.

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.

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.

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…

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

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.