www.kuro5hin.org/story/2003/9/29/104212/112
HOWTO: write bad documentation that looks good Technology By clover_kicker Tue Sep 30th, 2003 at 07:19:34 PM EST Intro In every techs life, there comes a time when management starts to insist on better documentation. 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.
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 Ws, ie 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. 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. 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, ie 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 youve encountered, or how you solved them. 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.
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? 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. 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 youve been trying to obfuscate. In practice, all such systems exemplify the flaws weve 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 doesnt 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.
Job Security by Obscurity none / 1 81 by vinn on Wed Oct 15th, 2003 at 12:20:58 AM EST Im starting to come to grips with the fact that my employer really doesnt care about its employees nor is my employment guaranteed in any way. Not that its much of a concern - no one else has ever bothered to ask for any of that knowledge. When I first started I kept meticulous notes, all nicely tucked away on my PC. Ive chosen to include really nice PDFs all culled from vendors websites. Thus far Im convinced no one has looked at the docs, they only seem to care that some exist.
This portion of your article reminds me of Tracy Kidders book, The Soul of a New Machine . Kidder was a journalist who got permission to hang out with and document a project at Data General that became their answer to the VAX. I thought it was a wonderfully written book - and a large number of people must have agreed - as it made the best-seller list. This book spent a lot of time conveying what it was like to be a newly graduated engineer, on your first full-time job, trying to meet an impossible deadline by spending a year working 60 to 80 hours per week. It did a pretty good job at conveying the excitement of a project where you lived on a combination of caffiene, anxiety and hubris. The really amazing thing about this book was its hidden dual nature. Both geeks and non-geeks loved it for completely different reasons. Both geeks and non-geeks read the same words and had totally different emotional reactions to it. Geeks, or former geeks read about those adrenaline fueled all-night debugging sessions, and felt a vicarious excitement, because it reminded them of their own adrenaline fueled all-night sessions. Non-geeks read about these adrenaline fueled all-night debugging sessions petrified with a horrified fascination, like watching a car-wreck, and felt a moralistic sense of superiority. They always knew geeks were fucked up and alienated, and the book confirmed it for them. No wonder scientists have fucked up the world if they cant even eat right and go to bed at a sensible hour. At least that was the reaction among my geek and non-geek friends and acquaintances. Yes, it would be interesting to hear how to craft poisoned documentation so excellently that no-one ever doubts that it was well done.
It takes two people, one a programmer, and the other a technical writer. The Technical Writer attempts to read it, if the Technical Writer can understand it, it gets sent back to the Programmer to be rewritten. The Technical Writer tries to read it again, if they can understand it, it gets sent back to the Programmer. Finally when the Technical Writer cannot understand a word of it, it gets sent to be published. I was told this was how IBM did their program manuals, I suppose it could work for program documentation too.
I was astounded at the quality of the documentation: major design decisions and justifications, ideas that didnt work, things to look out for all documented. This inspired me to keep a diary of my first few weeks at work, which contained things like the or...
|
http://csua.com/feed/