The project I've kept running the longest has almost no documentation, and the one I documented most carefully died within a couple months. I used to think that was a coincidence, but I've watched it happen enough times now that I don't think it is.
The heavily documented project got a README, an architecture doc, and a roadmap before it had a single real user. Writing all of that felt like progress, but it wasn't, it was a way to feel productive while avoiding the harder question of whether anyone wanted the thing at all. Once the answer turned out to be no, all that documentation became something to feel bad about deleting.
The scrappy project got zero docs because I was too busy actually using it myself every day to write any. By the time it had users other than me, the code had already changed shape three or four times, so any doc I'd written early would have been wrong anyway. Documentation caught up only once the shape of the thing actually stabilized, which took months.
I don't think this means documentation is bad, obviously a mature project needs it. What I've changed is the order: I don't write anything explaining a decision until that decision has survived being wrong at least once. Early docs describe intentions, not reality, and intentions are exactly the part of a new project most likely to be false.
Top comments (0)