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.
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:
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.