I had some plans for a massive web page on software and software management, but it occurred to me that it’d be better to blog about it instead, in dribs and drabs. So here we go.  (I should mention that though I’ve worked in the industry for 25 years, it’s all been in software shops.  I recently interviewed with a huge megacorporation that can afford to have 150 people paid to do nothing but write architecture documents; that’s another world and I can’t help you there.)

Today’s question is, why can’t programmers write documentation?  Are they just lazy, or what? 

The brief answer is, it doesn’t match how they think.  Programmers are good at dividing a huge problem into little pieces, chunklets simple enough to be understood by a pedantic idiot, that is, a computer.  It already takes a special mind to be able to think in terms of the little pieces and to master the petty, arcane way the idiot insists on being addressed in.  It’s rare that the developer can talk to human beings as well.

If you corral the programmers into a room and force them to address the lack of internal documentation– something they’ll readily admit is a Bad Thing– then they’ll come up with a way to make documentation look like code, or come out of code.  They’ll look at something like this method signature

public void Deposit(decimal amount) 

and produce something like this:

Method name: Deposit
Return value: void
Description: Make a deposit
Argument list:
     amount    decimal    (input)    amount to deposit

In other words, their idea of documentation is to list out what’s obvious to any programmer reading the method signature.  This does nothing except create something else to maintain or more likely to get out of sync with the code, but to the programmer it has the advantage that he can write a program to generate the “documentation” automatically. 

In a small software shop this sort of thing will be done for one or two code files and then quietly forgotten.

What do you do instead? 

If you really want internal design documents– and they are nice for training other programmers, for debugging, for sharing techniques– then you have to make time for them.  Developers don’t include design or documentation in the estimates they give, and since their estimates are low anyway, they’re usually skipped.  So include the documents as deliverables and make time for them in the project plan.  (Often there’s downtime at the beginning of the project anyway while the honchos are arguing over what to do, so that’s a good time for this.  This is also when the code is freshest in people’s minds.)

At my last job we had a wiki for design, ideas, documentation, whatever.  That works– at least, it works better than paper.  In this area the perfect is the enemy of the good: creating good paper documentation is difficult and time-consuming and people tend not to do it.  Slapping the best bits from an e-mail chain into the wiki, by contrast, takes only a few minutes.

The best place for documentation, though, is in the code.  Good programmers should explain what the major methods do, what the class is for, and any tricky procedures or formats, right in the code.  The code is where programmers look anyway, and since the comments are right there, they’re more likely to be maintained.  And it’s in the source control system and requires no extra tools.

(How do you get even that?  The surest way is to do code reviews, which I’ll talk about another time…)