
10 Reasons Why Documentation is a Startup Secret Sauce - naish
http://foundread.com/2008/04/08/10-reasons-why-documentation-is-a-startup-secret-sauce/
======
ten-seven
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.

~~~
mynameishere
<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.

~~~
pchristensen
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"

------
davidw
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.

~~~
mpfefferle
A wiki would probably work well. A Google Site perhaps?

~~~
davidw
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...

------
mpfefferle
This is basically the rational behind the E-Myth. Your business is not just
another job you do. It's a self-sustaining entity that you create.

------
angstrom
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.

~~~
Hexstream
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).

~~~
phaedrus
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.

------
edw519
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.

