Sunday, August 9, 2009

Why We Don't Document our Software

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.
  1. the documentation develops in parallel with the code
  2. documentaiton authors are rewarded equally with code authors (in non-material ways)
  3. 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.


  1. Doesn't quite work that way in the OSS projects I've been a part of - documentation always lags features. The key that differentiates OSS from proprietary is that there are documentation volunteers vs. coding volunteers. The devteam always vets documentation, but editing is so much easier than initial creation.

    For example, I'm heavily involved with the Perl distributions DBIx::Class and SQL::Abstract. I don't have time at night to code right now (though I have in the past), but I grok it all. So, I write specs which get turned into features by coding members and documentation by non-coding members.

    The proprietary systems I've worked on where documentation has been good have generally hired people specifically for documentation (both internal and external). Just like have devs be testers is a "Bad Idea"™, having devs be documenters isn't any better.

  2. What kind of documentation are you guys talking about? Documentation that explains how the program itself is written? Documentation that explains how the program is used?

  3. Yeah, there are many, many kinds of documentation, and I don't think they all fit into the same opportunity cost.

    One of the biggests assets documentation can provide is WHY decisions were made, and for this I find types of "living documents" more helpful than the specs we usually think of as documentation.

    So things like Basecamp, email, wikis, source control commits, etc. are more useful, albeit less centralized, than a 25 page Word document or something. But they always come out of real work than theorectical summary.

    I think the time to write formal documentaion is after a project has stablized, but before that the production of documentation and the material which feeds its should be a natural byproduct of development.


  4. Documentation serves different purposes. Sometimes to explain how to use a piece of software, sometimes it serves as ad-hoc project management, and other times it may explain project development standards. All useful, when necessary, and all have opportunity cost. That is variable depending on different factors.

    Documentation is neither good or bad. The value of documentation is going to differ, and be relative to an organization. Arguing against documentation as a blanket statement is a invalid argument, because documentation may be valuable in one scenario, and the same type of documentation may be waste in another.

  5. I like to write the user level documentation first. Then the results can be verified.

    Then the design documentation, so there's a map of how to write the code.

    The final step is to write & debug the code. If the other steps are done correctly this will be almost mechanical, thus the shortest and easiest part. (Some need for documentation up-dating might be discovered in this phase).

    A program spends most of its life in maintenance -- if its used at all. That's when having the documentation pays off in tangible results.