Supporting Open Source Software by Writing Documentation
Almost all of the software I use these days is Open Source; Free code runs this blog, most of the applications I use every day at work, and many of my hobby projects. While it’s great to get all of these power tools at no cost, I do try to support the ones I use a lot. In a few instances, I’ve actually been able to contribute little bits of code myself, but more often I try to pitch in where my skills are strongest: writing.
In most cases, I just end up answering questions from other users on a program’s support forum, email list, or Discord server. Having benefited from such help on numerous occasions myself, it seems like the least I can do to repay the collective favors of all those other helpful folks.
A little while ago, though, I found myself struggling through the setup and usage process for a powerful but cantankerous application for ham radio, a logging program called TLF. Hams like to keep logs of our on-air contacts, not only for the sense of accomplishment, but also as a prerequisite for various award programs and contests. TLF is built specifically for the latter.
TLF, a ham radio contest logging program.
In a radio contest, one tries to contact as many other hams as possible in a specific time period, usually 24-48 hours. While there are many layers of complexity and strategy to it, a key component of modern radio contesting is a logging program that allows the operator to record contacts quickly, while keeping track of their score and providing other data relevant to the contest. TLF is very good at all of those things, once you figure it out.
Unfortunately, TLF’s documentation had obviously been written by software developers, who were much too close to the code itself to understand what a new user needed to know. Things they hadn’t thought to mention took me hours to understand, and as I wrestled with the software I started keeping notes.
Soon, those notes turned into the type of document I wished I’d had at the outset, so after peppering the group’s email list with my newbie questions for a couple of weeks, I offered to overhaul their documentation. They accepted enthusiastically.
Having learned how to use this powerful program, I then had the opportunity to learn a few new tricks and workflows for using GitHub, and discovered a new way to collaborate with a team. I won’t claim that the current TLF manual is a masterpiece, but it’s a lot more approachable for newcomers than the old version.
It felt great to be able to give back to an Open Source project in such a direct way, and I’ve since been paying more attention to the different ways people can support this wonderful movement. Making and maintaining great software isn’t just about coding.