I know I didn’t invent the idea of “documentation-driven development”. There’s a solid chance I read someone writing about it, internalized the idea and forgot the source.[1] There sure are a lot of search results and I didn’t particularly recognize any of them.
At any rate, the idea is that as I add features, I’m adding to the Documentation at the same time. Sometimes I write how I think the feature should work first. Other times I document the feature I’m working on after I have it working. In either case I’m hoping the documentation for new features:
- exists and
- matches the way the site actually works.
Obviously this is useful for people trying to use the site, but writing documentation also helps me learn. Working though the steps and then recording them without the false steps and red herrings means I understand what’s going on. Even better, I can use that documentation in the future to remember what I learned. So too will any future collaborators.
As an aside, have you ever wondered how startups with one or two programmers get so much done so quickly? At least part of the answer is nobody expects them to write documentation. But that’s just one of dozens of shortcuts new products can take. For instance, I managed to slow down this site for a few minutes on Friday:
I’d been testing backup recovery and I started a second Discourse server on the virtual machine that runs this site. That wasn’t a good idea. There just isn’t enough memory to run two Discourse sites at the same time. But since the site has (virtually) no users, nobody noticed. Making mistakes like that is the luxury of a startup. Maybe that explains the legend of the 10x programmer. Startups fulfill the prophecy simply by hiring people into low-overhead jobs.
Documentation effectively markets the product. I can tell you my site will solve your problems, but the documentation will tell the truth of the matter. As I fill out the feature set, it only makes sense to show it off while also helping people learn how to get things done.
As my sixth-grade teacher, Mr. King, used to say, “Knowledge is that which remains when what is learned is forgotten.” ↩︎