This blog probably won’t stir up a hornet’s nest or anything, but I would also expect that it would be the least popular in practice. The person who feels they can disagree with the need for a reasonable amount of documentation is probably nuts. In the first post, I defined documented as “Anything that cannot be gathered from the previous four is written down and/or diagrammed for others”.  And yes, I know documentation is more boring than a whole oilfield of derricks.  So let me give you a life lesson. Documentation is fun when it is done BEFORE you build.

Yes, you heard me. If you have chosen names for things that seem right, the definitions you make may in fact just fall out of the name. So it isn’t that much work. The payoff is probably a lot better than you might imagine. And be careful though, TOO much documentation can easily be worse than no documentation. Sometimes systems have so much documentation that it is impossible to know how to even find information, or there are conflicting bits of documentation.  Keep it sparse, just enough information that you communicate what was on your mind when you were designing your objects. Some example benefits that I find:

• Names can only be so descriptive – You only get 128 characters for a name, and if you get close to that your users are going to beat you with whatever they can find handy.  Name should be succinct versions of the definitions. 
• Names should not usually include purpose – Purpose can be tricky. Who wanted this, why they wanted it, and how it is to be used can only be documented (or mined from the code later, I suppose, if you are REALLY patient and your programmers use really good comments.)
• While documenting your objects, you will be forced to (shudder) think one more time about what you are documenting -Writing down your meaning of what you have just designed after you are feeling good about it gives you a chance to give it one more look over, and this time in context of other stuff you have done. I often find one or two things per hundred (at least) that I go…maybe I was wrong. (Of course when I say it the sound in my head is more like Fonzie admitting he was wr..wr..wr..wroo…wwwr..Hey a guy has to have some ego.)
• Documentation should be written in a language that all users can understand – Sometimes in our names we use clever jargon to make the names more concise. Inheritance is a good example.  Ask the normal user what inheritance is any they will start fantasizing that their parents just passed away (in the best possible manner, of course) and left them a billion dollars. Clearly this is unlikely to be the meaning of this word unless you are creating a system to create a last will and testament.

The fourth is the magical moment (wow, too much Disney ).  You have your design you want to implement.  Your analysts and users are checking out the design to make sure they “approve.”  They see a lot of names, fine.  They see some diagrams, decent. They read your definitions and wait.  What do you mean by “this attribute is here for X”? Did we agree to that?

Well, yeah, I thought you did, you will indignantly think, but sometimes, no matter how sure you are that you are right (and really no matter how right you are that this was in fact the design you had agree on) the realization that a communication gap the size of you and your parents was somehow opened up and things went sideways.

I feel like I am repeating myself, but for you Agile guys, I don’t mean documenting things to death, or even spending all that much time.  If you are creating 30 tables with 10 columns on average, and 20 relationships, you only need to document 320 independent items. Add a bit more to the documentation for constraints, and then for processes, and you might have two hours of work. And if you DO find this taking too long, either you have messed up the first Pillar: Coherent or your team has real communication problems that can’t easily be solved by reading this blog.  And the more Agile you are, the more important coherent communication (which includes documentation) is. What happens if you get it wrong and cannot ship after a sprint because you didn’t get clear direction and your team didn’t realize it until they started seeing the “results”?  Pretty sure that can’t be good for the manifesto.

So yeah, all I am trying to say is that documentation is communication. Not just to you, not just to other programmers, but to future programmers, users, and even a future version of yourself that you would treat better if you could see the pain in his (or hers) eyes.