Re:10 Reasons Why Documentation is a Startup Secret Sauce
by ten-seven on Tuesday April 08, 2008 @10:04AM
(#157846)
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.
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by pchristensen on Tuesday April 08, 2008 @04:11PM
(#158239)
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"
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by davidw on Tuesday April 08, 2008 @10:46AM
(#157892)
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.
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by davidw on Tuesday April 08, 2008 @02:23PM
(#158104)
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...
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by omouse on Tuesday April 08, 2008 @07:04PM
(#158374)
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.
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by angstrom on Tuesday April 08, 2008 @09:32AM
(#157824)
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.
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by Hexstream on Tuesday April 08, 2008 @04:46PM
(#158272)
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).
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by phaedrus on Thursday April 10, 2008 @10:45AM
(#159913)
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.
Re:10 Reasons Why Documentation is a Startup Secret Sauce
by edw519 on Tuesday April 08, 2008 @08:31AM
(#157792)
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.
.............
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.
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).