Writing Jokosher Documentation

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.

Leave a Reply