Ask HN: How much documentation is enough?
3 comments
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)
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)
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.
I write short architectural papers as I go along, mostly to get feedback from interested parties. I do the "official" documentation at the end.
[deleted]
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.
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...