The Techaddicted Guide to Documentation

I’m forever telling my developer friends that “Documentation is not a dirty word!”. But, for most of them, documentation is that thing their managers tell them they need to do, that thing that gets in the way of coding, that thing that takes forever because they don’t know how to do it and the don’t want to do it. These same friends keep asking me “We’re falling behind schedule at work and so my boss wants to hire another developer — I suggested hiring a writer but apparently we don’t have the budget for that! How do I convince management that it’s worthwhile to hire a writer?!” I’ve previously written a blog post about this, but I realise it’s not enough.

So I put together a presentation that addresses two main points:

  1. How to write documentation – Because sometimes documentation is inescapable and it doesn’t need to always be painful.
  2. How to justify hiring a technical writer – Lacking hard statistics, but with a story and diagram.

I presented this at Tech Meetup Edinburgh back in July. You can watch my presentation below (30min, including questions) or you can just flick through the slides yourself (View Slides).

Denise Marshall talks about Documentation from TechMeetup on Vimeo.

NOTE: Most of my images are from XKCD. See http://xkcd.com/license.html for license info.

Words to Avoid

After my presentation, I got a few requests to share my list of Words-to-Avoid

That list can really be broken down into two categories:

  1. Ambiguous words – they have more than one meaning and both meanings are frequently used. But one way of using the word can be easily replaced with another, non-ambiguous word. Sometimes you need to use a word that has multiple meanings, but if you consistently use it to only ever mean one thing, then that goes a long way to helping keep things clear.
  2. Warning words – words that should warn you that your writing is in the wrong tense, wrong tone, or something else un-good.#

Lets start with the ambiguous words….

Ambiguous Words

Once

Once should only ever be used to mean one time. You do something only once. Though once upon a time doesn’t really belong in serious documentation. Most of the time, the word after is a perfect drop-in replacement for the incorrect usage of once.

Hint: If you use once at the start of the sentence, it’s probably incorrect. Sometimes it’ll be in the middle of the sentence. Every time you use the word once, think to yourself if you can replace once with after and keep the meaning of the sentence – if you can, then do it.

Good: Click the button once to save your document.
Bad: Once you’ve clicked the button,  the system restarts.

Replace bad of once with after

Correction: After you’ve clicked the button, the system restarts.

Since

Since is commonly used in conversational English to mean because. For example, “Since I don’t like peppers, I always have to pick them off of the veggie pizza” is fine for explaining that I am picking peppers off my pizza because I don’t like them. But since also serves as a great word for describing “time that has elapsed between this previous event and now” quite succinctly, such as in “I haven’t eaten since breakfast”. Because since can easily be replaced by because in some cases, the because sense of since should be replaced with because to make the usage of since in the temporal as unambiguous as possible.

Good: If you have not restarted your system since installing updates, do so now.
Bad: The updates have not been fully installed since you have not yet restarted your computer.

Replace bad since with because

Correction: The updates have not been fully installed because you have not yet restarted your computer.

May/Might

May and might suffer from the same problem — are you trying to say that it is possible that something has the ability to happen or are you saying that something has permission to do something. It’s like being back in school again and Miss is telling you “Yes, you can go to the toilet but no, you may not”.

Just forget about may and might and your Miss who’s making you hold it until lunchtime. Just use can and could instead. But when would you use which?

  • can for permission
  • could for ability

Good: You can create a new customer account.
Good: The system could crash if you do not create the order using the wizard.
Bad: You may create a new customer account. (Do you mean “You have permission to”? “You have the ability to”? “There is a possibility that you want to”? etc. So many different meanings!)
Bad: The system might crash if you do not create the order using the wizard.

Warning Words

Will

If you’re using the word will, it means you’ve slipped into future tense. Stay in present tense.

Good: The report opens.
Bad: The report will open.

Please

You don’t need to be nice in serious documentation.  Conversational writing can work for you, but be careful of humour in technical documents. Humour is difficult to read and is even more difficult to translate. If you’re including words like please, you may be slipping into other casual language. In technical documents, just stick to the facts.

Please implies that the reader does not need to do what you’re going to ask them to do and that you don’t think they’ll like to do it – you just need to tell them do do it.

Should

Nothing should happen. Either it can happen or it does happen.

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>