Documentation as a gateway to open source

Documentation as a gateway to open source

If you’re interested in getting involved with open source, contributing to documentation is a good—and helpful—place to start.
Part of
Issue 6 August 2018

Documentation

If you want them to RTFM, make a better FM.
— Kathy Sierra

One of the scariest moments of any engineer’s life is the moment before sharing their code with the world. Whether it’s a pull request for your employer or a commit to an open-source project, you’re about to open yourself up to feedback, debate, and sometimes even criticism. This can be especially scary for more junior engineers, fervently hoping they got everything right and won’t look stupid when they click “Submit.”

In a professional environment, you can (hopefully!) assume a limited and supportive audience for your contribution. In an open-source project, however, this might be your first interaction with the community. On top of hoping your code is acceptable and useful, you often don’t know the standards and norms, who the players are, or the collection of odd processes and esoteric rituals—like those around approval workflows and house styles—that develop in many communities.

There is a way, however, to reduce the fear, make a good first impression, and learn more about a new open-source community: writing documentation. Documentation is a vital part of any project. Yet few open-source projects can claim they are well documented, and many others struggle to keep their documentation up to date. (Some notable exceptions include DjangojQuery, and SQLite—these are worth looking at as model examples.) Documentation is also the entry point into a project for most people, and a lack of good documentation inherently limits its reach. By contributing to documentation, you can help attract new users (and potentially new contributors) to a project.

It’s important to mention that this article assumes you want to get involved in open source. This is a complex decision for many folks, especially those who don’t have the economic or logistical flexibility to contribute. The spurious association between contribution to open-source software and employability is also a concern. I recommend this excellent article by Ashe Dryden as a starting point if you’re interested in these issues.

With that said, let’s look at some ways you can start contributing to open source through documentation, starting with how to find projects to work on.

Finding a project: Contribute to what you know

My first exposure to many open-source projects is via a need. When looking for new projects to work on or determining who might need some help, I usually start with projects that I am using or intend to use. I might have a feature to build or a problem to solve, and I ask myself: “Is there prior art? Can I take a shortcut by ‘buying off the shelf’ instead of building myself?” I google or search GitHub and find a repository that contains a library or tool that might help. I then examine that repository to see if the project meets my needs, and I usually do a quick health check on it, too, to see how well it is maintained. If the project seems to meet my needs, then it’s time to try it out. By using it myself, I can start to identify whether I can improve the documentation or make life easier for the next person trying it out. I find it ideal to make contributions when the project and my experiences in implementing it are fresh in my mind.

I also recommend using referrals. If you have friends who work on open source, they’ll often know which projects are friendly to new contributors and might make a good place to start.

You can find a number of good examples of open-source documentation and other excellent resources at the Write the Docs community.

Once you’ve found a project, you’ll want to keep in mind some basic contribution etiquette as you get started.

Etiquette

Approaching a new project can be less stressful if you take a couple of preparatory steps.

First, do some research. Many projects have an issues backlog that details what the project needs—often including gaps in documentation. This is a great place to get ideas for what to work on. It can also give you a sense of the people involved in the project and how other contributors have interacted with it.

Second, review any contribution guidelines. A lot of projects outline these in a README file or a CONTRIBUTING file. These files usually contain instructions on how to contribute to the project—guidelines on where and what to branch, testing, and continuous integration, or community standards like code linting or formatting. The instructions should help you ensure that your contributions are in line with community standards.

Third, ask where the community needs help. You can follow up on an existing issue, for example, by asking if anyone is working on it and volunteering to help or seeking clarification on the best place to start. Or you can contact the maintainer(s) directly and enquire about specific problems or areas they might need help with. Be aware that many maintainers have day jobs or limited time and may not respond immediately. They may also have been offered help in the past that hasn’t eventuated, so sometimes folks can be wary. But most maintainers are super excited to get new people involved in a project.

Sometimes you won’t hear back from a maintainer if you just reach out or update an issue. I tend not to let this stop me from contributing, though that’s a matter of personal preference. I use the information available to me to contribute something, and I find that a pull request often triggers more activity than an update on an issue or an email. In these cases, I recommend providing a lot of context on and explanation of your contribution so the maintainers understand your intent.

Of course, there are open-source projects out there that are not welcoming or friendly. If you get a response or observe behavior in a project’s issues or pull requests that makes you uncomfortable, you’re under no obligation to contribute. Move on and find another project.

Now let’s look at some areas where you might be able to contribute.

READMEs

The first place I start when trying out a new project is the README file. Many (or most?) open-source projects have a README file in the root of the repository. Sometimes this file consists of instructions on installation or usage. In larger projects, it might include directions to the project’s resources, like documentation, releases, or a project website.

As I install and use the project I take notes on what works, what doesn’t work, what steps are missing, and the general structure and coherence of the documentation. After the installation, I use these notes to update or rewrite the README file. I usually fix:

  • Spelling, grammar, and formatting.

  • Installation and usage instructions for correctness and coherency.

  • Organization of the overall document for first-time users.

Here’s an example of the sort of rewrite that’s useful. Here is the README beforehand, and here is a pull request showing my updates. As you can see, I’ve addressed a number of both minor and major issues with the existing README: I’ve tackled some spelling errors and formatting issues, and I’ve corrected or expanded upon instructions. The end result is a much more readable and coherent document that will help others use the project.

Strings, errors, and commands

If you want a low-risk entry point into the code itself, then the strings, error messages, help text, and other non-code language elements in a project are ideal. These elements are another of the project’s interfaces with its users. You want the usage and help text to be clear, and the error messages to articulate the actual problem that is occurring. This isn’t limited to help or usage text, either. A lot of projects have APIs with built-in or generated documentation using tools like Swagger. A fresh set of eyes on API descriptions, examples, and error messages can greatly enhance their clarity. Additionally, fixing spelling and grammar issues in those elements can make the project look more polished. Here’s an example of a Go binary with some issues, and a pull request that fixes those issues.

Other ideas for getting started

In addition to these areas, here are some other potential contributions you could make:

  • Adding or updating FAQs.

  • Creating HOWTOs and tutorials.

  • Creating or updating documentation or project websites.

All of these are areas in which projects often need help and lack resources, and they can be great places to contribute. These areas also serve as an excellent introduction to the codebases of these projects. And once you’ve contributed some documentation, contributing code, features, or bug fixes to the project can become smoother and easier.

If you’re interested in getting started with open source, I hope this article gives you a sense of how contributing to documentation can help you get your feet wet while making a meaningful impact on the usability and approachability of open-source projects.

About the author

James Turnbull is VP of engineering at Sotheby’s and the author of 10 technical books about open-source software. Previously he was VP of engineering at Timber and Glitch, CTO at Microsoft for Startups and Kickstarter, and CTO and founder at Empatico.

@kartar

Artwork by

Justina Stasyk

justynastasik.com

Topics

Buy the print edition

Visit the Increment Store to purchase print issues.

Store

Continue Reading

Explore Topics

All Issues