The Jokosher project has a development site using Trac. It’s a good setup for software developers because it combines a source code repository with a wiki, allowing code, bug-tracking and documentation all to happen in the same place. We did most of the documentation for Jokosher 0.1 there on that site.

Before the next release, though, Jono wanted to have a separate documentation site. This minimizes the number of people who need accounts and SVN access on the developer site. It also gave me the opportunity to look into a setup better tuned to documentation, rather than software development.

We settled on using MoinMoin, mostly because it supports DocBook/XML natively, is written in Python, has great theming support and seems to be actively developed. We used two wikis, one at http://doc.jokosher.org that has been themed to look almost exactly like Jokosher.org, and a second at http://userdocs.jokosher.org that looks more like a wiki.

The first site appears to the “casual observer” as just another page on jokosher.org, but it can easily be updated by me without giving me FTP access to the server. It also lets me post documentation in DocBook/XML, which we couldn’t do with WordPress.

The second site will be open to anyone who wants to edit, and will give us an easy to use place for documenters to collaborate. As new documentation is finished it can be moved to the main docs site for users to access.

Eventually this will all be integrated to look like one congruent web site, even though it’s 3 sites (jokosher.org, doc.jokosher.org and userdocs.jokosher.org) on 2 different pieces of software (WordPress and MoinMoin).

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.

I’ve been working on writing documentation and organizing a documentation team for Jokosher these past few weeks. Jokosher is truly a “scratch your own itch” type of project, conceived to fill a need for a simple, usable, intuitive audio editor on Linux. It is by musicians, for musicians (and other audio artists).

Open source projects are always in need of more help, and documentation is usually lacking or lags behind the software. I thought I’d say a bit from a documenter’s standpoint on why I got involved with Jokosher in a world full of projects needing docs help.

• They made me care – I know the people behind Jokosher and I trust them. I heard about what they were doing and thought it was going somewhere. So many projects start and go nowhere. From an idea over a year ago to the first commits in February, Jokosher has come together and generated excitement. In a few days it will make its first release. It’s V0.1, but it works. It’s a project I can care about that fills a real need. There’s a community around it that shares a vision to do something different and better.
• They made it easy – I’ve tried to contribute to an open source project before where I had to fight just to help people. Questions did’t get answered, information on getting involved wasn’t easily available, bug reports sat forever without action. I submitted a patch and didn’t hear anything for weeks. With Jokosher, there’s a good mailing list, the website has up to date info on getting involved, and the developer’s site has lots of information. For the most part, information on what needs done and how the project is moving forward is easy to discover.
• They rewarded me – Once I started writing and submitted a patch for the User’s Guide, I got an E-mail saying thanks immediately. For an hour’s work I got a thank you. I never failed to feel appreciated. When I dropped into the IRC channel (#jokosher on freenode), people said Hi and where quick to answer questions. Jono even mentioned me in his blog and gave me credit for my work. My name is now in the credits in the Jokosher Help menu. The other project I worked on included my work, but I was never given credit anywhere.
• They lowered the bar – The documentation for Jokosher was opened up for editing on the Wiki. The documentation itself is all in HTML, which is far easier to deal with then Docbook/XML. That’s not to say we won’t go to Docbook eventually, but to get a project off the ground, making it easy makes a difference. If I had to sit down and edit Docbook on my home system, validate it, then submit a patch I don’t know if I would have bothered. With the docs on a Wiki available on the internet, I could work anywhere at anytime.
• They gave up control – Having documentation that can be edited by anybody is a leap of faith. Sure, with a Wiki you can roll back changes, but you still have to give up an element of control. What if someone writes reams and it’s just horrid? My first patch was committed within hours. No one stood over my shoulder and told me what to do, they just let me roll. I got helpful feedback, but I never felt like I was a puppet just doing someone else’s work.
• They challenged me – I have a friend who studies leadership in a small to mid-size group context. He told me there are a small but significant (~15% of population) number of people with leadership ability who will show up a couple times and if you don’t challenge them they’ll go elsewhere. Some people need something to do or they won’t stick around. I think a lot of geeks are this way. Once I started submitting work, Jono sent an E-mail thanking me and asking me if I could work on revamping the documentation pages on the Wiki and fleshing out a “Getting Involved” page. It was a bit more than I had planned on, but it was the push I needed to move to a deeper level of commitment. To me, that’s what team building is about. That’s what makes community – getting people involved and committed to the project so it means something to them.