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.

I was minding my business on the internet when I happened upon a review of the new Microsoft Manual of Style for Technical Publications on Kai Weber’s Tech Writing Blog. It was an interesting review (you should go read it) so I thought I’d have a look at what the going price is for the new Manual of Style.  A Google search for Microsoft Manual of Style took me to the Microsoft webpage on the third edition where I saw a bit of text that had my inner-editor shouting “NO NO NO!”.

Use technical terms correctly and consistently—including do’s, don’ts, and alternatives for usage.

When I was first taught about the apostrophe, the rules were simple:

1. An apostrophe signifies a contraction
   Example: “I cannot” contracted to “I can’t”
2. An apostrophe signifies possession
   “Alice’s new shoes”

But as I got further in schooling, there seemed to be this grey-zone of plurals which seemed better with apostrophes. Wikipedia mentions some such as when pluralising lower-case letters:

Be sure to dot your i’s and cross your t’s

It’s certainly not the “grocers’ apostrophe” that raises the hackles of copyrighters everywhere (Apple’s £1.50/lb). Surely nouns shouldn’t ever require an apostrophe to be pluralised… But what about those grey-zone ones?

Is the phrase do’s and don’ts correct in its punctuation?

It seems to me that it’s the pluralisation of do that seems to visually require the apostrophe. Without it, it risks being mis-read as a mis-spelling of does, or perhaps (Microsoft) DOS.

I, personally, would use DOs and DON’Ts, relying on the difference in capitalisation to make it easily readable. But which is right? I struggle to think of any other phrase that requires the pluralisation of do, this shortened phrase that means “A list of things to do and a list of things to not do”. Using the capitalisation also invokes the image of two side-by-side lists, topped by the words DO and DON’T. But does anyone agree with me?

I did another quick Google search for Do’s vs DOs to see what what the forums of English pedants might suggest. Here’s a quick summary of  the first few  Google hits:

Site	Do’s	Dos	DOs
EnglishForums.com	Y	N	No mention
Answers.com	Y	Y	No mention
BeeDictionary.com	Y	Y	No mention
DemocraticUnderground.com	Y	Y	No mention

To be honest, a lot of the forums in the first page of hits seemed more concerned by the Don’ts, assuming that there SHOULD be an apostrophe in do’s so should it be written don’t’s. And no one seems to care about my solution of DOs.

Conclusion: These days, it seems like you can do whichever makes you happiest with this particular phrase. Oh, well. It’s a good thing I don’t use the phrase in documentation.

When I walked into the office kitchen yesterday, I overheard some of my software developer comrades discussing Language Log. As I made my way to the coffee machine, one of them asked me “Hey, are you the one mentioned in that Language Log post about ‘Every Little Helps’?”

Completely caught off-guard, I sputtered “uhm, yeah.”, thinking back to the day that I brought the topic up with a lecturer after class, and he posted about it on Language Log to find out what it was all about.

“I KNEW it!” he exclaimed in response. “Though I’m sure there are only so many American undergrads named Denise Wood studying Linguistics in the UK… Cool!” I couldn’t help but wonder to myself if this is the single greatest moment for me in the field of Linguistics, a name-check on Language Log. Instead of an Erdös number, I’ve got a Language Log number of 2 — Though I’ve never posted (not even replied), I was written about by a poster on language Log.

The discussion around the coffee machine then went on to discussing syntax, until another programmer walked into the kitchen and we realised we’d been standing there far too long and rushed back to our desks.

I’m OK with the fact that I’m not really pursuing a career in academia, where I can say “I am a Linguist” when people ask what I do for a living. I’m a technical writer, I work with software programmers. I still get to spend all day thinking about language and how we use it, though. I also get to have these beautiful moments when I realise that the polymath is not a thing of the past — my programmer friends read my favourite blog and can discuss linguistics with as much comfort as they discuss maths, chemistry, and code.