A brand-new book called “Subtleties of Scientific Editing,” by Matthew Stevens, has come out in PDF. You can download a copy at http://www.zeta.org.au/~mls/subtleties.html and if you like it, pay the few dollars that the author requests from satisfied readers.
Having spent decades writing user documentation for software companies, I found a lot of relevance, but some differences, in a book based on decades of editing scientific papers.
One difference is that Matthew complains the first person — “I” or, more normally for a scientific paper, “we”— isn’t used enough. He quotes Fowler’s Modern English Usage, which says that avoidance of the first person “often amounts to a pusillanimous shrinking from responsibility ... The person addressed has a right to know who it is that entertains a feeling he may not share or a thought he may consider mistaken, and is justly resentful of the suggestion that it exists in the void.”
A product’s manual generally doesn’t exist in a void where unattributed statements have no obvious authority. Like Woody Allen, who in Annie Hall can speak confidently about Marshall McLuhan because Marshall McLuhan is right there to back him up, the manual speaks confidently about the product’s behavior because the manual comes with the product. If the manual speaks about something else, though — if it drops a remark like “Twenty percent of the world’s computers have a virus” — then just like a scientific report, it does owe the reader a source. And if the manual is issued by someone other than the manufacturer, then the author must anticipate the same questions as the scientist: “What makes you so sure? Who told you? Did you try it yourself?”
If a manual from the manufacturer does say “we,” the reason could be another good one that Matthew mentions: simple, conversational communication. It’s more natural to say “We advise backing your data up daily” than “It is advisable to back your data up daily.”
But whereas in a scientific report, “we” clearly means the credited authors, a product’s manual generally has no authors named. So the reader may imagine “we” to mean the company as a whole, or to mean some individual writer using the editorial “we,” or to mean any plural entity in between. Just as you would define any acronym on first use, it’s best to define who “we” is — “we at Neckwear Techware Limited,” for example — and to stay true to that definition.
(Are you, as a technical writer, entitled to proclaim that you speak for the whole company? You speak for it de facto anyway, but whether your company lawyer is paying attention is another question.)
Once you’ve established the meaning of the word “we,” don’t allow other meanings to creep in. You could inadvertently find yourself using “we” to mean people in general (“We seldom check whether our backups work”) or to mean some previously undefined part of the company (“The support team will forward your comments, and we will act on them”). Or you could slip into what Thurber called the clinical “we,” which means “you” and is always offensively condescending (In the hospital, “Have we taken our medicine?” Or in the manual, “Next, we will learn about backups”).
If you or your team may have trouble sticking to a single definition of “we,” or can’t elegantly use it often enough to keep it from startling the reader when it does appear, then avoid the word entirely. It’s no great loss, because a writer of user documentation can establish a good conversational tone based on a word that most writers of scientific reports don’t have at their disposal: “you.”
Comments and questions are welcome: ]]