As part of my day job I produce technical documents, proposals and RFP responses for a (mostly) non-technical audience. I read and review even more of the above from sub-contractors, professional services consultants and technical support. I’m as likely to split an infinitive as the next person, but there is stuff I see on a daily basis which drives me crackers. Here are some of the worse crimes against documentation (in my opinion).
- Documentation should always be written in the third person. Bad: “I believe this is the issue.” Better: “It is believed,” or “It is understood.”
- Statements should be definitive, prescriptive and confident. Ambiguity over any point does not help anyone. For example, “This change may help, or it may not,” gets you nowhere. Try instead: “To progress the issue, Company Foo recommends that the following actions are taken.”
- Don’t ever not use double negatives.
- Always show you’re working out – not “This will fix it.” Cite references if you have any. Provide a short rationale behind the recommendation. Make sure you have a rationale.
- Be succinct. Ask yourself the question, “Does this sentence contain redundancy?”. Try to avoid sentences that go on and on and on without any punctuation or come to any point and if read aloud would cause the reader to hyperventilate.
- Eschew obfuscation.
- Do not be afraid to point out the worst case scenario. Documentation is an excellent way to cover your arse if something is not being done properly. If it’s written down, it’s official. Do not cry wolf.
- Keep your own copies of documentation revisions; don’t rely on version numbering, “track changes”, or a centralized copy. This will save time and effort when you need to find out how and when it changed from “the ISP manages the routers” to “the ISP doesn’t manage the routers.”
- Learn how to use bulleted lists, indexes and section breaks. These are word processing basics. They can be a PITA, but will save you time in the long run and make for a much more professional end product. Use cross references to refer back to other sections in the document. This makes the whole document flow together much better.
- Pick a font and stick with it, as long as it’s not Comic Sans. Reading Arial on an LCD screen feels like my eyes are being scratched with toothpicks. Only use bold and Italics if absolutely necessary. Even then it’s probably not necessary.
- When describing an issue or incident:
- Describe the problem.
- Discuss the impact.
- Offer possible courses of action.
- Make a recommendation and justify it.
- Don’t make a recommendation which you are not able or prepared to defend in person.
- Use the spel checkr. Don’t rely on the spool chocker. Proof, proof and proof again. Then print it out and read it again, aloud if necessary. You would be surprised how many errors still creep into “finalised” documents.
- “Track Changes” is your enemy. It will ruin the flow of the document when it is being reviewed or edited. Typos are one thing. Ask for comments on your documentation rather than getting someone to edit it into oblivion. It’s difficult to understand which changes have been made and why, and you don’t learn nuffin if you accept someone else’s changes wholesale.
- Make sure your title and contents pages match the actual content of your documentation. Documentation evolves; this is OK. Just remember to update the scope accordingly.
There is bound to be other stuff I’ve missed or forgotten; I welcome any contributions, additions or abuse. If I have committed any other crimes, please feel free to point them out in the comments below.
[Editor's note - errors you might notice, including the title, are there on purpose to help make the author's point.]
About Glen Kemp
