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.
A wiki would probably work well. A Google Site perhaps?
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...
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,…
I prefer to keep that number at ONE, so my co-founders have an incentive not to kill me.
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,…
http://c2.com/cgi/wiki?TruckNumber ............. 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"
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.
Most of my code is "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).
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.
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.
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.
A wiki would probably work well. A Google Site perhaps?
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.
A wiki would probably work well. A Google Site perhaps?
We recently implemented a wiki for our project and it's been a big help.
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.
Most of my code is "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.