Reasons Why

Less is More


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 live sex show 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 jasmine live 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.

Don't forget...

Always assume the user knows how to do something. say to get report A you need to first edit query foo with the special program that automatically updates it to the current date. in the documents you list it as "To recieve report A, update foo to the current date." assume that they know about the special program that automatically updates it for you instead of pouring over the 15000 line query looking for every mention of the date. (extra credit if only one entry is relevent) You've included several examples that are not only informative but also believable and interesting to read. They're almost like real-world usage scenarios even. You've gotta just resist the temptation to ever provide examples of what to do or what not to do. That's key to writing bad documentation! Also, never offer suggestions to the reader/user, let alone one that's a "Concrete Suggestion". Yes, definitely, put the headings and content there so it looks like you've included plenty of examples and suggestions. But, never include any useful content. That's the key: be incomprehensible. If you're really good, then write everything in passive voice using only ambiguous, multisyllabic, multi-word nouns and adjectives and form your verbose sentences as convolutely as possible. This practice ensures the person or persons using the ideas contained in the documentation comprehend the point the writer was trying to make in only a small number of cases and successfully implement the procedures a far lower percentage of the time, while simultaneously appearing impressive and educated to the casual manager's eye (your "shiny things" statement). This practice is sometimes referred to as self-obfuscation.

Wish I'd had this a couple years ago...

I was working at a medium company working hard to become a small company when they told me to document everything I did. The best part was when they took all previous documentation and threw it out before asking me to re-document the same process. Apparently they decided I was so successful at this that the laid someone else off, stuck me with his job and asked me to write the documentation there too, at the same time updating procedures and trying to pass ISO. Mind you, at the time I had never written any kind of documentation before at all so having no example from which to template my work was oh so helpful, particularly when they stuck me with a new job and wanted me to write documentation, which I had never done before, to do a job I had also never done before. I'm glad you said that! The tech writer at my company seems to think that the word facilitate is appropriately descriptive for various program features. It's the perfect word -- It describes WHAT you're doing (facilitating), WHY they would want to do it (to make it easier), and eliminates any need to understand what you're actually documenting. Example: The netmask field is used to facilitate the entry of your networking information. You get bonus points if you include a screenshot with a helpful.