We have a concept we call our "Bus Number." It's the number of people that know how to do what you do, or have been briefed on what you're doing, so that if you're run over by a bus, they can pick up what you're doing. It's a grim concept, but it highlights another point: what happens during the startup period should a key person fall ill, or die? Good documentation could save the shop and make sure your dream lives, at least for a while longer.
Anyway, documentation is all well and good when it takes the form of a "how to". That seems to be what the author is getting at. But there's just nothing worse than reading or writing documentation that consists of proposed method signatures, object structures, or anything in any way related to UML.
He's referring to business process documentation, which is different than code documentation. Coding (or design in general) is different than operations and can't be documented as precisely. It's the difference between "Here's what I did" and "Here's what to do"
Nice article. Author doesn't mention one key point: your documentation MUST BE SINCERE. Nothing is more hilarious (and will derail you faster) than some B.S. mission statement on the front door.
What do you guys use for documentation, btw? I used DocBook for Hecl, but man is it ever a PITA. It's very, very, very, verbose, and even if that verbosity does give you a lot of flexibility, I'm not sure it's worth it in terms of docs that don't get written because it takes so long.
It might - but I'm curious about what people have actually used successfully and any limitations things they've liked about a particular system. Maybe it's worth it's own post...
If you're an Emacs user I would recommend Muse mode. It uses some special markup but it can output HTML, LaTeX, PDF and another format or two. It's also like a Wiki with the links.
Personally, I'm suspicious of anyone who doesn't document what they did. If you are unable to take the time to leave a trail of your thought processes and reasons then the understanding you claim to have about your domain is suspect. The only exception is if it's throw away code.
In the sense that even if it's about the best code I can produce right now, in a couple months I'll have learned so much and improved the rest of the system incrementally so much that my formerly-best code I will need to throw away (as in refactor or even rewrite).
Document it anyway! Although it might seem like a waste of time to write about something that will change, the fact is that all software is potentially throw-away code. That's the "soft" in software - you can and should change it if it needs to change. If didn't document things that might change, you'll either never document or you will be loathe to change code that has been documented. Instead, just look at both the code and the documentation as a working sketch.
