Writing documentation is a good way to start contributing to an open-source project. Documentation may have been overlooked or written as an afterthought during the software development process, so there are usually many opportunities for you to help enhance the content.

Users of all experience levels and skills have perspectives that are valuable additions to the documentation. By contributing your knowledge, you are making the software more useful and accessible to everyone.

Bailey the cat thinks the help needs more information about yarn and boxes.

Where to start

The code and accompanying documentation for many open-source projects are stored on github.com, which is a website that enables project collaboration. If you are new to GitHub, consider making your first open-source contributions to documentation or the README file because they likely have simpler setup requirements than attempting to modify code. Even if the code is mature or closely guarded, its documentation may be more welcoming to modifications. You need to create a GitHub account to get started.

Sometimes, you will find documentation files alongside the code, while other projects have a separate repository (the term for the grouping of files, folders, and data that makes up a project) for documentation. When you find the repository you want to work on, review the contributor guidelines to learn about maintaining a positive community environment and the process to follow to propose changes.

Contributor guidelines for the Pelias project, which is an open-source geocoder that powers Mapzen Search.

When you are ready to propose updating the source file with your changes, open a pull request. A pull request is the way you notify others about your suggestions. The community managers then review your changes and decide whether to accept them into the source. This feedback helps them discover what is important to users based on what the community is looking at and are updating in the documentation.

What to write

While reading the documentation, you might find simple errors like typos and broken links that could be resolved relatively quickly. Other times, you might encounter a tutorial step, API version number, or screenshot that is out of date. Unfortunately, you might hit something that is completely wrong or missing. You can fix these yourself if you have time, or report problems or enhancement requests to the project’s managers through GitHub issues.

Beyond fixing issues in existing documentation, adding new content is another excellent contribution. If you are an advanced user, perhaps you can write tips, shortcuts, and detailed workflows. As a beginning user, share what you learned to make the ramp-up process easier on others. Adding tutorials, enhancing installation instructions, giving sample code, and building troubleshooting sections are very helpful. In addition, translating documentation into another language can bring a project to a new set of users.

You might also look for GitHub issues that have been tagged with Help Wanted, which indicates external assistance is requested. These lists can provide suggestions on what to do when you want to help an open-source project but are not sure where to start.

How to update Mapzen’s open documentation

You can find Mapzen’s technical documentation at https://mapzen.com/documentation. The source files used to build the site are stored as markdown (.md) files on GitHub, and are formatted into what you see on Mapzen’s website.

The bottom of every page on the Mapzen documentation site has a link where you can view and edit the source file. Follow these steps to contribute to the help.

1. On any help topic, click Edit this page on GitHub to access the source markdown file.
   
   
   
   
2. Sign in with your GitHub account.
3. Click Edit this file to enter a mode where you can modify the page. GitHub automatically creates a copy that you can edit.
   
   
   
   
4. Add your updates and save them (also known as making a commit into your fork of the file).
5. Open a pull request when you are ready to propose your changes.

There have been dozens of community contributions to Mapzen’s documentation so far! Looking through the documentation repositories, you have submitted pull requests resolving typos, formatting problems, and unclear API input parameter descriptions.

In addition, you have logged GitHub issues relating to API enhancements, unexpected API responses, and differences between the text of the documentation and the actual API result. You have also posted questions about how to localize the API text string values because you want to help with translating them. Some of the documentation issues you reported were traced to problems in the software, so both the documentation and code were improved with your help.

Thanks to all of you who have contributed to Mapzen’s documentation so far—and the documentation for other projects. Community support is fundamental to an open-source project’s success.