Jono has been writing lately about open source communities and how to make it easier for people to get involved. While I could quibble with the details, I agree with the principle. People contributing to open source projects shouldn’t have to deal with technical details. Art guys should know the intricacies of Inkscape, but not SVN and bugzilla. Coders should (just) deal with code, documentation people should deal with documentation.

From the documentation perspective, I don’t agree that documenters don’t need to know markup languages.

To me, writing documentation is a form of teaching. A documenter’s job is to instruct the user in how to do what they need to do. Documentation should make things clear, spur ideas, and empower. It should give the reader mastery of the software and enable them to integrate it into their brain as a tool. Documentation should do all this as quickly and clearly as possible.

To meet this end, document writers need to be as structured and organized as possible. We need a high level overview of the problem so we can break it down for the reader. We think in terms of the hierarchy and flow of a document. Just as an essay needs to have an opening paragraph, supporting points and a conclusion, a User’s Manaul needs a certain sructure that follows the way a user will look for help.

So a markup language of some type is essential. Be it HTML, wiki markup or DocBook/XML, we need to be able to structure documents. The problem is most markup languages suck. HTML works great for web pages but it makes sloppy documentation. Wiki markup is quick and easy, but it’s too limited. DocBook/XML forces the writer to use good structure and hierarchy, and takes care of a lot of the tiresome details (like table of contents, and nearly all presentation markup) but the learning curve is pretty rough. It is needlessly complex for most things.

The solution?

We need more accessible tools. For documentation we need a more usable subset of DocBook, or maybe a whole new XML application designed for software documentation. I hear something like this is in the works. We also need editors that can handle whatever format we settle on. I’ve tried various editors and in the end I’m more productive editing in Vim and doing all the markup manually.

If we’re actually going to solve these problems we need to do away with the edit-patch-submit cycle altogether. What we’re doing in Jokosher is a good example. We did almost all the documentation for 0.1 on the wiki, then generated our final docs from that. It still required a lot of manual work to get from wiki output to the final HTML, though. Now that we’re moving to DocBook/XML, the situation is worse. We’re building a new site that will support editing HTML and DocBook directly on the wiki, but the tools are still not there yet. We will need to modify existing tools to get what we want.

We need an infrastructure that supports contribution, but who builds this infrastructure? I’ve seen good projects suffer because there are people who would love to contribute, but just can’t get their foot in the door. Again, the Jokosher project has solved some of these problems. We’ve taken the time to write “Getting Involved” documents to give people step by step instructions to contribute. We’ve got forums and wikis and clear documentation for developers. All this stuff takes time away from development, but building a community that allows people to get involved means a better project in the long run.