Open Source Participation: Documentation is a good first hurdle

Last week I wrote about the lack of manager-types in open source, and how it can make it difficult to maintain/begin participation. This was an extension of my New Year’s resolution post, which detailed the fact that I want to participate more in open source. I decided on a couple of projects (GeoServer and Habari), and started lurking on their mailing lists and spending a little time on their IRC channels. I realized that it had been over a month, and I claimed that I was going to do some open source participating, but I had yet to do anything substantial. To combat my procrastination, I set a challenge to make a simple text update and submit it as an alteration to the GeoServer documentation. I think it worked well.

The story goes: I posted an article about Configuring GeoServer on AWS, and got a couple of comments about JDK support. This led to a comment from me that included some misinformation - but when I checked the GeoServer docs, they turned out to be the source of my misinformation.

Documentation is a great entrance to an open source project

The bold text is important, don’t forget it. I asked some questions on the GeoServer irc channel, and got helpful feedback regarding the documentation inaccuracies and how best to resolve them. Then I set out to make an update. GeoServer has pretty good documentation overall, and they just revamped their system away from a wiki and to a sphinx implementation that allows documentation to participate in the VCS (subversion). This turned out to be great for multiple reasons. 1) The documentation updates included helpful modifications to the documentation guide (how to work on the documentation) and 2) This meant that I gained experience with the GeoServer VCS and patch submission, which was helpful experience since I hope to get into the code eventually.

So, following the documentation guidelines, I should have downloaded the src and installed the tools for generating docs. When an issue is identified, write a bug in JIRA @ codehaus, make the fix locally, test the fix locally, and then commit the fix to svn. Some places where I could have easily given up, in chronological order:

  1. Creating a codehaus account. A/B testing experts know that registration can be a double-edged sword. This did not phase me very much, but I can see hesitation here. Don’t hesitate, just register and get on with the bug logging.
  2. Creating a bug. A bug creation style-guide was not apparent (caveat, I do not recall looking very diligently). I adore QA, and did not want to offend anyone with an inconsistent or incomplete bug. The bug got a quick comment from a project lead, and was resolved later, so I assume it was at least reasonable. If there were more daunting concerns in the bug generation (fields for which I was unsure, etc.), I would have likely gone back to irc with a couple questions about where I can find a bug style guide or who could assist me with my questions (now that I think about it, this is backwards - I should check the docs first, then go to irc).
  3. After creating the bug, I set about making the change. This involved installation and a little learning of sphinx and its markup. The actual text change was trivial, so I did not really need any markup knowledge, but it was a worthwhile exercise. Using the documentation provided on the GeoServer site, I was able to get up and running and make the changes without difficulty.
  4. Here was the major sticking point for me. The GeoServer documentation suggests committing your change once it is ready. But elsewhere in the documentation, it is indicated that you need to submit a few patches before asking a project contributer to grant you commit rights. I am still not certain if I should have asked for commit rights or submitted a patch. I submitted a patch. I think I will hop back on irc soon, and see about working with someone to clean up the docs a little and prune some of the bugs that pertain to legacy documentation - which I assume does not warrant updating. We will see.
  5. After I submitted the patch, I played the waiting game, but not for very long. The waiting game can be dangerous, if I had not signed up for all the mailing lists, or disabled notifications, I might have stopped there, and not ever looked back. This highlights another good thing about the documentation edits, they tend to happen quickly. Documentation updates are pretty well contained and testing for the updates is simple - unlike code updates, which necessitate much more critical review. Someone closed the bug shortly after I submitted the patch. Even though they did not use my patch, they did update the text to address my concern, and I did log the bug and submit a patch (challenge acheived).

There were a couple of sticky spots in the process where I admit to feeling like my efforts were hardly worthwhile. This is somewhat accurate, since it was a miniscule update, and probably does not make much difference to very many users. But, a positive comment regarding my efforts was added to the JIRA issue upon closing, and paired with some helpful feedback on irc, it was enough to keep me running. It also gave me a great opportunity to get some irc interaction on a few very concrete questions, and to get a feel for the GeoServer issue tracker. Disclosure: I happen to have used JIRA quite a bit, although never at codehaus.

My next challenge is to inquire on irc and the mailing list about assisting with JIRA cleanup for the legacy documentation. There were a lot of old issues logged that pertained to legacy docs. As I said, documentation updates can be a great way to start supporting a project. Upon analyzing documentation, minor errors are often more apparent to untrained eyes. Unlike a contributor deeply entrenched in the project, you will not glance past small inconsistencies or missing steps. These updates are also beneficial because writing good documentation forces you to become more familiar with the project. This learning effort helps you to better understand the project, and the documentation updates (and issue resolutions, in this case) help the project progress.

So I plan to close some issues (if that is appropriate, need to check with project leads/participants), make any necessary doc changes along the way, submit patches for those changes, and possibly edit the documentation guide to include details about submitting patches vs. committing code directly to svn. I will let you know how it goes.

1118 words

geoserver teachingopensource