Defensive Writing

  • Article

One of the facts of life when you write technical documentation and guidance is that it will get reviewed by other people, resulting in regular changes to the content as you try to follow shifting advice, conflicting feedback, and suggestions that sometimes even make sense. It doesn't help, of course, if the technology you are documenting is also a moving target.

I don't profess to be an expert in all the technologies we cover, but I generally have a good grasp of the fundamentals for each one - such as what it's supposed to do, how it does, it, and how you can use it. But I depend on reviewers and feedback to make sure I covered all the relevant points, and that what I've written is accurate as well as being useful.

Over the years, I've come across many situations where it's useful to write defensively in order to minimize errors and illogical content, and to reduce the work required to get the stuff finished and out of the door. While they might not be applicable to everyone, here's a few things to think about:

  • Don't include a number in the introduction to a list. The number of items will change. A list of four items that starts "The following four types of data store..." will look silly after you add another one in response to reviewers' comments and forget to change it to "five".
  • Look out for overuse of your favorite words. I found I'd used "encompass" three times in one paragraph before I proof-read it. Use a thesaurus (even the Word built-in one) to find equivalent words and phrases.
  • Beware of including numerically accurate information such "costs x" or "is x times faster" because it will be wrong next week. Words such as "considerably", "minimal", and "cost-effective" are often just as useful.
  • "At the time of writing..." makes sense only to you. Put the date in.
  • Check out commonly accepted information before you accept it. For example, Hadoop was originally created at Yahoo!, not by Apache.
  • Beware of your "only" positioning:
    • "Only developers can use feature x to confirm the results" (nobody else can use feature x to do this)
    • "Developers can only use feature x to confirm the results" (developers can't modify feature x)
    • "Developers can use only feature x to confirm the results" (developers can't use any other feature to do this)
    • "Developers can use feature x only to confirm the results" (developers can't use feature x for any other purpose)
  • Leave all the comments in until you go to release. You'll get conflicting feedback from different reviewers and you need the history to figure out why you changed something in the document, and what actually is correct.
  • Get inside your reviewers' heads. Some will comment only on the bits that interest them, so you can't assume the rest is accurate. Others will offer half-thought-through or off-topic suggestions that are not directly relevant (but might be useful elsewhere). Look out for hobby horses and special interest comments that will bloat the content without adding anything useful. Lazy comments such as "You need to cover other stuff here as well" but don't say what you missed probably need to go back to the reviewer, but don't expect much additional help.
  • Beware of the cleverness of word processors such as Microsoft Word. Removing a comment can sometimes insert a space, which can be a problem in code listings. Deleting the word before a word that starts with punctuation (such as ".NET") removes the space before the word. For example, deleting "Microsoft" from "the Microsoft .NET framework" results in "the.NET framework".
  • Minimize deep linking by linking to the home page of another site where possible, and tell the reader where to look, as long as it does not make the reference unusable. For example, "See the documentation for feature x on the [link]targetsite.com[/link] website or "Search [link]targetsite.com[/link] for "Configuring feature x". You get fewer broken links this way.
  • If you use numbered figures or schematics, and don't (or can't) use the automatic figure numbering features of your word processor, minimize the times you reference the figure by number because you'll add and remove figures over time. You can start the paragraph before or after the figure with "This screenshot shows..." or "In this schematic, feature x is ...". Referring to a figure in a different topic by number is risk taking at the extreme.
  • Proof-read your content in more than one format. If you proof it only in your word processor, you'll probably miss errors that become obvious when it's displayed as HTML. I'm not sure why this is - perhaps it's to do with word positioning due to the layout and line wrap. Or familiarity with the content in the format and layout where it was originally created.

And finally, my own hobby horse: always remember the phrase "Time flies like an arrow but fruit flies like a banana". Use "such as x" rather than "like x" when giving examples of things...