There’s a running joke among my development teams:

Mockingly, we act out the following scene:

Customer, or other interested party asks:

“You have a question about the software?”

Developer, tech writer or other knowledgeable party replies:

“Yeah. The answer’s in the doc.”

All other interested people within earshot chime, in unison:

“Of course it is, but who reads the doc?”

After this exchange, I always smile, shrug my shoulders, and go back to writing more of the doc. I got my job in large part because I have a fairly impressive array of English degrees, assuring those in my company that I could write some coherent documentation. But does anyone read the doc?

Writing a technical document is difficult. Reading documentation that is poorly written is even more difficult, and likely more challenging than writing it. It takes diligent effort to create clear, accurate prose that engages readers, and if it is software documentation can it ever be engaging? Does anyone want to read this stuff? I have trouble imagining the scenario where someone is eager to sit down and sink into a piece of thrilling prose about how to install a new update! But I suppose anything is possible…

While there are a handful of guides out there to improve your prose, I thought I would start my January off with just seven little “rules of engagement” that I try to keep close at hand when I write Software Documentation.

Now, bear in mind, this does not apply to all writing. I just mentioned to a colleague the other day that I may not win any awards this year for great American fiction (though I do have an upcoming creative nonfiction essay due out in April, but I’ll clue you all in to that later. This advice is strictly about Technical Publications, and more specifically in the narrow field of software doc. (Forgive me, I had some fun with the links – see, finding the fun in technical documentation?)

1. Dry is for deserts – You read that right. While you don’t need to pepper your doc with humor, sarcasm or literary devices, it also needn’t be free of lubricant. Write in first-person, use active verbs, and try to paint a picture for the user. In other words, do not write uninteresting prose.
2. Imagine what your reader will do before you write – This will help you write clearly. If you can envision the process, you can create the words. Walk your own self through the steps, and use that as a guide.
3. Prepare an outline, just like in college – I wrote outlines for every other kind of writing, so w
   hy stop now?
4. Avoid ambiguity always – (I’m dying to mention something about alliteration, but I won’t) This is a big one. Just be clear, and everything will be, erm, clear. I used to teach my creative nonfiction students that it was supremely important to not just choose the word but to choose THE word. That still rings true.
5. The road to clarity is through a combination of words and illustrations – If a picture is worth a thousand words, imagine what a picture PLUS some words will do for you! Add a graphic or a diagram, and the technical prose you create is just pure magic. If you are explaining a tough concept, map it out.
6. Tough concepts require logic, so use it – Get a good book of logical explanations  (An Illustrated Book of Bad Arguments is actually a really good one)nand apply them. Do not ever stoop to saying, “That is as simple as it gets,” because that is just not true. Make a concept simple, and then make it even simpler. That’s the job, after all.
7. Look at revision like it’s your best friend – If you cannot enjoy the art of revising, then this job is just no fun. The whole idea is to try to shape and reshape and finesse ideas in fun and innovative ways. The work is never done, or we will work ourselves out of a job. One day, all of the doc will be written, so if there is no revising, there’s no more work. Until, of course, there is more software! So thank goodness there is always more software!

Continue reading →