Rich, Famous, and Popular
Posted by Greg Wilson on 2010/01/17
Almost everyone who joins a new project says it sooner or later: “More documentation, please.” No one can make sense of 30,000 lines of code in one gulp: everyone wants an overview or roadmap to help them make sense of things. So why don’t they exist?
- Almost by definition, by the time you can write that document, you don’t need it yourself. You probably also have a dozen tickets assigned to you by then too, all of which really, really need to be fixed for next week’s release.
- Overviews are much harder to write than lower-level Javadoc-style explanations of what individual methods do. The latter is just an assemblage of facts; the former requires story-telling skills, and good storytellers are rare in any field (not just programming).
- Anyone who ever has written an overview document knows that it will rust pretty quickly. Design decisions will change, code will be refactored, and pretty quickly, that 30-page tutorial you sweated over is so far out of date that it’s actually doing as much harm as good. Keeping it up to date is a never-ending struggle, and it’s not like people have stopped assigning you tickets…
Jacob Kaplan-Moss (from the Django team) wrote a good post a while back about writing great documentation. It’s worth reading, and he’s right: after a certain point, investing effort in documentation and discussion actually pays a bigger dividend for open source projects than investing effort in code. It’s still an open research problem, though; anyone who ever figures out how to generate, check, and update narrative explanations of how code is structured, what it does, and (most importantly) why, will be rich, famous, and popular. Lemme know how it goes…