Writing good documentation is hard.
Your management does not understand how complicated the situation
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
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.
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.
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
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.
An ounce of disorganization is worth a pound of confusion
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.
Document the existence of this script
Document what inputs the script requires
Document what output the script produces
Document what condition the script was written to detect, or the
consequences of that condition.
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.
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.
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.
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.