Documentary films, when successful, offer the viewer an intimate glimpse into a situation as it unfolds. There is often a progression or growth that occurs through the film, as every mistake and every twist and turn is captured candidly. It’s captivating because it tells a story “as it happens” instead of recounting or remembering a story after it has happened.
So why should software documentation be any different?!
Imagine a film documentary where the director didn’t really think anybody was going to watch it, so they half-ass the editing process or just decide to skip filming some days. The end product would be a pretty incomplete documentary. Sound familiar?
The analogy may sound silly, and I doubt any software documentation will be as interesting as a well-made documentary film, but why is most software documentation so BAD? We’ve all encountered confusing, vague, incomplete documentation and the reason is most likely because people regard documentation as an afterthought. It is often minimalistic and leaves out many details that the general reader needs - more a footnote for the original author than for anybody else.
This makes for really boring or confusing documentation. Since the author is documenting something they have just finished, the information is not thorough or particularly valuable. They (developers and users) want to know what the author was thinking when they wrote it, why they wrote it, pitfalls, and would like to understand the author’s experience in a compact form. This means not glossing over details, and it also means not providing unrelated or distracting information.
It may seem like a daunting process to document software, and that is probably because:
a) Developers are allergic to writing.
b) Developers enjoy being as cryptic as possible (d0cum3nt4t!0n i5 14m3, d00d!!!)
c) People try to document things after they happen, which feels like a lot of work.
While I’m sure a) and b) have something to do with it, people more likely write bad documentation because they try and do it after they are finished. Nooo! It’s like taking a fascinating video documentary and summarizing the entire thing on a post-it-note. Somehow, not as thorough… ;)
It’s really easy to write good documentation, and the secret is to *document things as they happen* and not after they happen. If you notice something or realize something while you are working, just write it down somewhere, keep a running list, and most importantly: DON’T LEAVE ANYTHING OUT. Even if you think it’s obvious, it may not be obvious to the next person, and sometimes it’s not even obvious when you go back and read it yourself! Remember that you are documenting a process, so editing things out is NOT encouraged. Later on if you need to, you can go back and edit things that are extraneous or confusing.
The amazing thing about this process is that it FEELS like less work, because you aren’t forcing yourself to remember things. In some cases, it can help you plan out what you are working on, too.
Five Steps to Writing Better Documentation
1) Write things down as they happen.
If you are describing how to configure something, actually walk through it yourself, keeping clear notes as you go. Keep a running list somewhere, and don’t leave out details. The extra few seconds after each step to document will pay off later. Additional information like screenshots and simple examples help immensely.
2) Try not to make any assumptions about your audience.
Provide relevant details or links to background information where appropriate. If you do make assumptions, state them at the top, i.e. “This document assumes the reader has a working knowledge of PHP.”
3) Organize the results.
A simple outline (you know with roman numerals and stuff) works well. Try to envision a newbie reading your documentation, then a more experienced person. The idea is that good documentation works in levels - so that a reader can see the “big picture” immediately but also can examine the details if they need to.
4) Revise, revise, revise.
Documentation evolves over time. Your audience may be unclear about how something works or why you did something or may need more details. Keep revising until they stop bugging you! :) This is the stage where you trim the fat, so to speak.
5) Put on your scarlet smoking jacket.
Bask in the everlasting glow of your work with a glass of wine near a crackling fire.
You don’t have to be an expert on a subject to write good documentation. An expert tends to automatically make more assumptions, but newbies have a fresher perspective. Since most readers will be newbies themselves, they’ll be able to relate to the author’s tone and language as well. On the other hand, experts can explain things more thoroughly and concisely from a technical point of view. Both perspectives provide valuable insight on how something works.
Lastly, have fun with it! Throw in some jokes or drop a reference to P. Diddy once in a while. Reading this stuff can be agonizing so your readers will thank you for waking them up. ;)
Much like the parent who gives their child the keys to the family car, there comes a time in our client engagements where we set up administrative accounts for our clients to begin managing their own content. At Chapter Three we call this 
