6 Ways to Improve Documentation

Documentation is very important, and can often get pushed to the back of the queue only to be forgotten. However, this only becomes a problem later when someone tries to figure out just what this thing is supposed to do.

Here are six ways you can improve your documentation easily and quickly:

Embed help into your scripts. When you write a script (Perl, ksh, Ruby, et al) provide a help screen that is printed when the script is run without arguments, or when run with one of the arguments -h or –help … or even -help or -? (though the first two are best). Also document the purpose and other details within the script itself.

Write to your audience. Remember when you write who your documentation is. Most of the time, this will be a junior administrator (or someone who fits that description, title not withstanding). However, sometimes this will be an executive (which demands a different set of knowledge and context).

Document in more places. When writing documentation for a script, write the documentation in all of the logical places (not just some). Here are some logical places where your documentation should be:

• Inside the script (function descriptions, syntax, arguments, etc.)
• During script operation (using -h or –help)
• Man pages (man myscript
• Info pages (info myscript)
• (VMS) Help system
• (Windows) Help files
• System technical documentation (how does the script fit into the entire environment or system)
• System overview (does this need to be changed?)

Use paper. Create printed documentation - the system itself will not necessarily always be running. When you need help, it might not be available online. The best documentation will also include printed source as well as the general documentation.

Encourage people to use it. If the documentation gets used, then it will have served its purpose well. It also allows you to ask people what they thought of it, and to improve it. This becomes a self-perpetuating review process for the documentation writer.

Just do it! Okay, so that’s a stretch - but if it doesn’t get done, you won’t have any (now there’s a statement!). Some programmers, administrators, and analysts may think they don’t have the time. However, you must make time - if you don’t, the person trying to comprehend just what this thing does might be you.