October 03, 2003
HOWTO: Write Bad Documentation That Looks Good
clover_kicker, kuro5hin.org, writes:
In every tech's life, there comes a time when management starts to insist on better documentation.
Perhaps a round of layoffs or outsourcing is imminent. Perhaps the simmering disdain between techs and management has escalated into open hatred. Either way, you are clearly on the way out, and management wants to grease the wheels for your successor.
Objectives
You wish to produce documentation that:
will impress your management, and facilitate your remaining time in that job.
will not substantially help your replacement(s).
does not betray obvious signs of sabotage.
General Principles
Writing good documentation is hard.
Your management does not understand how complicated the situation really is.
Your manager sincerely believes that more documentation is better.
As the amount of documentation increases, so does the effort required to maintain it.
To fully understand any situation, you need to know the 5 W's, i.e. Who, What, Where, When, and Why.
In general, documenting "what" is not nearly as valuable as documenting "how" and/or "why". "What" can be discovered with a little effort, but the reasons "why" are often obscure and complicated. Your most valuable asset in your current job might be your detailed understanding of why everything is set up the way it is.
Complex systems generally have several interdependent components. Often, the relationship between these components is a tricky affair, finely tuned after months or years of tweaking.
Concrete suggestions
More is not better
It is easy to produce impressive quantities of paper by documenting the very obvious and/or completely useless.
Spend lots of time on the appearance and presentation of your documentation. Your management is easily distracted by shiny things, and will not realize that your binders contain information that could easily be recreated by anyone.
Creating bad documentation is time consuming, and makes you look very busy. You can use your documentation as an excuse to avoid real work, or perhaps to con a few more days of employment.
One insidious consequence of overly detailed documentation is the maintenance required. Recording trivial changes is very time consuming. However, unmaintained documents quickly become inaccurate and misleading, arguably worse then no documentation at all.
Example 1
A sysadmin could make a binder for each server with serial #s, driver diskettes, partition images burnt onto CD, etc. Include lots of obvious hardware and software settings, i.e IRQs, driver revisions, patchlevels, IP addrs, MAC addrs, etc.
Routers and switches should also get a binder with appropriate h/w and configuration information.
A programmer might bulk up documentation with information about trivial internal functions and macros.
Never tell "why"
Never describe what problems you've encountered, or how you solved them.
Do not explain what task each program or machine is doing. Do not explain the interactions of any systems, or which programs/machines depend on other programs or machines.
A programmer should never call attention to global variables, or functions with side-effects.
Example 2
In the past, there have been problems with running out of a particular resource (disk/RAM/bandwidth/whatever) on a particular machine. You have written a script to help predict when this problem is about to occur.
do:
Document the existence of this script
Document what inputs the script requires
Document what output the script produces
do not:
Document what condition the script was written to detect, or the consequences of that condition.
extra credit:
Modify the script to examine additional machines and/or resources. This will help obscure the true purpose of the script.
Parameterize the script so that it can examine several different machines and/or resources. Make the default action something plausible but irrelevant, and manually provide sensible parameters when you invoke the script. If your script is a cron job, make it produce a few extra reports every day. The more automagic logs one receives, the less attention is paid to them.
An ounce of disorganization is worth a pound of confusion
You can achieve maddening results by carefully fragmenting your documentation.
A well-written "principles of operation" document that describes the big picture is worth a million pages of detailed trivia. Your "special" documentation should therefore meticulously detail the trees, while scrupulously ignoring the forest.
Example 3
Would it be more frustrating to learn Unix system administration by only reading man pages, or an overview which referred to specific man pages where appropriate
Which would cause more grey hairs
A network diagram listing all servers, and their IP addresses
A set of detailed documents, one per server. Each server document consistently records the IP address on page 13.
Which of these documents is worth the paper it is printed on
A 1 page document listing all global variables
A large document with a detailed entry for each variable, listed alphabetically.
Theoretically, your trouble ticket system contains all the information you've been trying to obfuscate. In practice, all such systems exemplify the flaws we've discussed: poor organization, too much irrelevant detail and too little discussion of "why".
At best, your trouble ticket database is full of sketchy problem descriptions and meaninglessly vague resolution fields. More likely, the ticket database is an incoherent work of speculative fiction that doesn't contain records for many changes.
Afterword:
Most technical documentation suffers from the above flaws without even trying to be evil. Commercial software documentation is execrable, and in-house documentation is worse, especially when produced in accordance with a formalized documentation standard.
The above article is a satire meant to help you write good documentation. Honest.