It starts with a phone call, frantic email, instant message, or personal visit. System X is down. The programmer for system X left the company 5 years ago and nobody has touched it since. If it doesn't get fixed soon the widgets will start sprouting legs and marching on IT. They'll be torching the place shortly if you can't fix it fast!
Quick, where's the docs? Um. . .
"this space left intentionally blank"
Yeah, it really stinks. If it hasn't happend to you yet, just wait, it will. It's ironic since as a software developer I'm proud to work in a very rational field. Software Engineering is one of (if not the) most logical profession in the world. You would think we wouldn't allow this kind of chaos to happen. But we do. All the time.
Because we are so logical the fact that we rarely document our work therefore can not be perceived as illogical. As noted in a previous post common excuses such as: poor writing skills, too busy, etc, don't stand up under scrutiny. There must be a rational, logical explaination.
In economics they teach a principle called "opportunity cost". Whenever a choice is made there are always other options that are excluded. For example, during the years I studied software engineering I simultaneously lost opportunities to study other subjects. More pertinently, the hours spent writing documentation are not spent writing code.
Software Engineers are hired to write code. The flashier, cooler and showier the better. Writing documents may earn a polite "atta boy" from the boss (followed by "how's project X coming along"). The only way to earn real kudos is to deploy code or rescue the company from a dire emergency. (The irony is that many of these dire emergencies are created by undocumenttion.) From time to time we may out of guilt write some docs, but inevidably we gravitate towards the rewards, leaving behind a wake of sparsely documented systems. What is unusual is not the lack of documentation, but the documentation that does exist.
The solution is breathtakingly simple: treat documentation as the equal of coding. The open source community has already illustrated that this can be done. Since I haven't been a part of an open source team I can't verify this personally, but from an external view I see some factors at work that I don't see in software for hire.
- the documentation develops in parallel with the code
- documentaiton authors are rewarded equally with code authors (in non-material ways)
- the documentation is highly visible to the people handing out the rewards
If we can find ways to implement these concepts inside software for hire shops my bet is that poor documentation will become a thing of the past.
P.s. Anyone out there already doing good documentation I'd like to hear some suggestions. Pleas post a comment.
