

Ask HN: How much documentation is enough? - mooders

I'm interested in how much technical documentation startups generate during the pre-launch phases. I'm particularly interested in YC invitees as they are in a very timebound context.<p>In my one-man setup, I generate enough documentation to sketch out the main user flows through the app; a broad technical architecture and a feature roadmap. I do not document detailed technical and functional spectifications, nor do I write detailed test cases.<p>I guess the question I am asking is whether I am storing a world of pain for x months / years hence by adopting such a lightweight approach...
======
pmjordan
I've found that when I write documentation as I go along, I tend to document
the wrong things. It's a bit like premature optimisation: you're in the thick
of it, hyper-focused on whatever seems the hardest part of the problem at that
stage. You document what's on your mind. As with optimisation at that stage,
you're usually wrong.

So I've found you need to try to develop a sense for the sweet spot: the point
in time where things have settled down a bit and you're seeing more of the big
picture, yet it's all still completely clear in your mind and your memory
hasn't been diluted by the muddy waters of time.

I suppose for a startup, the key here is the _time where things have settled
down a bit_. I have no startup experience to speak of, but the impression I
get is that that time can be a long way out. Almost certainly longer than you
expect, as you iterate again and again and try to figure out what it is that
users _really_ want.

The other thing you need to ask yourself is why you're writing the
documentation in the first place. Is it for potential future developers? The
documentation isn't going to replace digging through the entire code for them.
Most if not all documentation that I've encountered which attempted to serve
this purpose was woefully inadequate and basically redundant. _If the code is
well-written, it usually documents itself, and if it isn't, you need to read
it anyway because it's probably impossible to encapsulate all its subtleties
in prose._

So internal developers are out. Who else comes into contact with your tech?
Well, maybe you have non-programmer cofounders/employees who need to generate
data in certain formats. You'll need to document those, no doubt, once the
formats start to stabilise. Better still, get users of the docs to write them
for you or with you. This sounds lazy, but actually their thought process is
different, and future users will think more like them than you. Of course,
check over the result for errors and inaccuracies.

Another group of people that will need documentation appears if you have some
kind of outside-facing API. These people will usually not have the opportunity
or inclination to trawl through your source, so as with the file formats
example above, to the intended readers of the docs, the docs are the _only_
source of information. I guess this one is really obvious, but I'm going to
point out that the design of your API will be more important than nailing the
docs for it. Iterate. An elegant API requires little introduction.

So these days I worry more about the quality of the code than the
documentation, and I write docs only for those who won't come into contact
with the code directly.

(NB: you can probably tell I've given this sort of thing a _lot_ of thought,
and have had extended discussions with other developers about the subject.
Take all of the above with a grain of salt - many people will vigorously
disagree with a lot of it. I'm also working on a project off-and-on that kind
of explores this space; unfortunately earning money to stay alive is consuming
my time at the moment)

------
russell
What you are doing sounds like the right level of detail. When I take over a
project, I like to have an architectural overview so that I have a context to
work from. Detailed but wrong is worthless. One important piece that I often
find missing is a short narrative about each table in the database.

I write short architectural papers as I go along, mostly to get feedback from
interested parties. I do the "official" documentation at the end.

