Strategy matters. If we’re not careful, our technical writing will be full of uncaught errors, wishful thinking, misplaced emotion, inaccurate promises, and unhelpful vagueness. This not only irritates our customers, it lowers our credibility: “Are they lying to us, or are they just incompetent?”
How does this happen? In several ways. It happens because we plunge into writing projects before we’re up to speed on the topic, then unknowingly write up our misconceptions. It happens when uncritically believe what the experts tell us. It happens when we need to say something, so we say…something.
And if that weren’t enough, the product changes out from under us. Things change and we aren’t told. Things that were supposed to happen, don’t, and we aren’t told. The scope shifts. The intended audience shifts. The sales pitch shifts.
“But the review process will save us, right?” Don’t count on it. The review process is weak, necessary but not sufficient. It finds only a fraction of the blunders. This is a fact of life. Exhorting others and ourselves to be more perfect doesn’t work. It just adds denial to the mix.
Most reviewers are capable of only one solid review, if that. With the best of intentions, their eyes will glaze over when they try to go over it thoroughly a second time. They’ll be able to focus only on the changes, and then only if they’re clearly marked. And this applies to us, too. We hit diminishing returns quickly.
So what can we do?
Defensive Writing
I usually write my documents from scratch: no one took a stab at it before I did. I often have a requirements document for the feature I’m documenting, and maybe an engineering spec, but these are internal documents not intended for customer use.
Still, starting from a blank slate lets me to choose my ground and pick my battles. One thing I pick is the avoidance of self-inflicted wounds. I call this aggressively defensive writing.
So here are my guidelines for aggressively defensive writing:
Don’t make promises about the future (beyond the next release)
My documentation (and maybe yours) is supposed to be nonfiction. We can make it considerably less fictional by leaving out all the aspirational stuff that isn’t locked and loaded. If I’m documenting an upcoming release, that counts as the present day for my purposes, but the release after that doesn’t. I try not to mention it at all.
Similarly, I don’t list dates except for the actual release I’m documenting, and then reluctantly and only in one place. If I start scattering dates all over the place, I’ll surely miss some when it’s time to update them.
Aspirational dates that use only the month or quarter are usually a mistake with technical documentation. No one really expects a how-to product document to embed roadmaps and release schedules. Such things are corralled in their own documents.
Be Sparing with Placeholders
One fact of life in the writing business is that some of the stuff you need to remove before the document goes live, isn’t. Customers and management will see it.
Therefore:
- Don’t put anything you wouldn’t want to be read out at a customer meeting in your drafts. No jokes, no grumbling, no whining.
- Use as few placeholders as you can. A “TBD” here and there is often unavoidable, but you don’t want “picture goes here” placeholders, especially if they’re still there months or years later. You’re better off if the placeholder was never there in the first place.
Don’t Use Bad Text
When you need to say something in the current section but don’t have the information you need to say it fair and square, it’s tempting to either make something up that matches how you hope the product works, or to put in some kind of vague gibberish. Both are mistakes.
If you use wishful-thinking text, even people who know better are likely to accept it if it sounds logical, so it’s likely to slide through review uncorrected. This may be even more true of gibberish, since reviewers won’t know what to do, exactly, with your fluffy meaninglessness.
Set the Scope of the Document to Match the Available Information
When writing up a new feature that hasn’t left the lab yet, I’d like to give the customer some best-practices advice for gaining the greatest practical value from it, but this isn’t actually known yet. What to do?
If I can get my hands on the feature and put it through its paces as a customer would, which I always do if I can, I’ll have at least an inkling of what the best practices are. If not, I’m just guessing.
Either way, having a formal “Best Practices” section is premature. It’s a task for later, when we update the document. As for my tentative best practices, I give them as examples, without using the “Best Practices” label. That’s honest.
This approach of documenting only what we actually know unless positively forced by necessity is especially effective if we structure our documents to present this limited scope as if it were perfectly natural, removing vestiges about what we wanted to include, but couldn’t.
No Pro Forma Content
Which brings me to my next tip: No pro forma content. Sections that don’t say anything useful to the customer shouldn’t exist. Unless forced, don’t take official templates or your predecessor’s willingness to waste the customers’ time as gospel.
For example, I almost never use a “Conclusions” section and I often don’t have an “Introduction” section, either. (I always start a document with at least one introductory paragraph, but I don’t bother with a heading unless the introduction becomes pretty massive.) I never use the “tell them what you’re going to tell them, tell them, then tell them what you told them” format, either. It just trains the readers to ignore your summaries.
Omitting pro forma content is also useful when dealing with reviewers. By presenting them with nothing but real content that’s supposed to provide genuine information to the customers, and by minimizing repetition, they’ll know that you mean it.
“Just the Facts, Ma’am”
Dragnet was a 1960s cop show where the detectives would remind people to focus on the facts. “Just the facts, ma’am” entered popular culture. In technical documentation, it’s it’s good advice. Instead of toying with the customer’s emotions through hype, or assuaging our own emotions by making excuses, it’s best to stick to telling the reader what the product actually does and showing them how to use it, and doing it as simply and clearly as we can.
We don’t have to be boring about it, but it’s a mistake to tell the customer that a feature is wonderful or exciting. They won’t take our word for it, and every time they reject one of our claims, they trust us a little less. We should be telling them things they can trust, in a tone that sounds trustworthy, never pushy or desperate.
This comes in especially handy when describing nasty bugs or frustrating limitations. It may take a couple of passes, but laying out the facts of the product’s misbehavior calmly, even blandly, is our friend. Yes, the news may upset the customer, but they should be upset on their own initiative, not because we prompted them!
Longer Documents
With short documents, especially ones that can be done in a few hours, the above advice is probably good to go. Longer ones need a scaffolding of structure and especially placeholders to keep you and everyone else from becoming lost. So the “no placeholders” rule has to be dispensed with for a while.
My preferred method is to create an outline and then instantly convert it into a storyboard: that is, to convert it into a formatted though rather empty document, usually in Word.
For example, the document’s headings would be converted into standard Word styles like Heading 1, Heading 2, and so on. The synopsis of each section would get a custom style called Synopsis, which I’d put into italics to set it off from the actual draft. This allows people other than myself to understand what’s being asked for in each section. Once a section is fully drafted, I delete its synopsis.
If I’m asking other people to provide tables, screenshots, or diagrams, I’ll add empty rectangles with a description of what I want, or tables with just a header row, to show them what I’m looking for and the context in which it’s used. If I’m going to provide them myself, I often omit these placeholders, since their need will be obvious to me as I write the section.
The trick here is to provide enough structure and a synopsis of what each section is supposed to hold, but without pretending to be the actual content. By putting the sadly inevitable placeholder material in its own styles, fonts, and perhaps colors, it’s less likely to slide into the shipped document.