Document by Blog: Writing by People

Working on this weekend, it became clear to me that open source projects need less formal documentation not more.

Rails is documented by blog, and by that I mean that while there are some great books, the bulk of the documentation you’ll stumble upon is blog driven. Especially documentation about very recent features. To learn about memcached and rails you read this blog. To learn about RedBox dialogs you read this blog. To some this is no documentation at all, but I think that this is better than having to refer to some incomplete static document housed by a project (see Apache Tomcat) or the confusion of Maven documentation. One thing is clear from dealing with the Rails community, every piece of documentation I’ve stumbled upon is task-oriented and written in the first-person perspective.

What I’m taking away from this is that the best project documentation is none at all beyond Javadoc. Seriously, the best documentation for something like Jakarta Commons would be the API. The home page should resolve to the JavaDoc. And, anything beyond that you can find with Google. Having worked on documentation for a few open source projects, it is a hassle. Programmers don’t care to write, and there is always a confusion about perspective. Most open source projects have this mismash of perspectives – some documentation might be written in this an odd first-person (which makes no sense for a project), the tone isn’t consistent. Most open source documentation reads like a poorly edited Wiki page.