Activity: Find an Open Source Project
In this course, you’ll do a variety of activities to build your skills, develop content, and gain experience. Many of the activities in this course will require you to work on documentation related to an open-source project that you find.
Without this project, it will be difficult to do many of the later activities in this course.
- Reaching your larger goals
- Finding an open-source API project
- Criteria for the open-source project
- Don’t undervalue your doc skills
- Search for an open-source project with API doc needs
- Contributing will require Git skills
- More reading
Reaching your larger goals
You’re probably going through this course for one or more of the following reasons:
- You want to break into the field of API documentation.
- You want to develop your API doc skills for a future job.
- You have a new API to document at work and need information on how to do it.
- You’re a developer who needs to document your API.
For the first two scenarios, you need to start thinking about API documentation samples in your portfolio. Your portfolio is key to getting a job in API documentation. Without a portfolio with compelling API documentation samples, it will be extremely difficult to get a job in API documentation.
How will you generate API doc samples for your portfolio, without having a job developing API documentation? This is where the activities in this course become important.
Rather than simply completing modules and tracking your progress toward the course’s completion, I’ve included activities here that will actually help build up your portfolio with API documentation samples, helping you progress to the goal of either obtaining an API doc job or hitting a home run on an API doc project in your current role.
Finding an open-source API project
If you’ve already got an API project through your work, or if you’re an engineer working on an API project, great, just select your existing API for the course activities. However, if you’re breaking into API doc or building your API doc skills from the ground up, you’ll need to find an open-source API documentation project to contribute to.
Finding the right project can be challenging, but it is critical to your portfolio and your success in breaking into API documentation. Fortunately, almost all open-source projects use GitHub, and GitHub provides various tags for documentation and “help wanted” in order to attract volunteers. (The task is actually so common, GitHub provides advice for finding open source projects.)
Criteria for the open-source project
The ideal open-source API project should meet the following criteria. The project should:
- Involve a REST API (not a library-based API or some other developer tool that isn’t an API).
- Have some documentation needs.
- Not be so technical that it’s beyond your ability to learn it. (If you already have familiarity with a programming language, you might target projects that focus on that language.)
- Be active, with a somewhat recent commit.
Don’t undervalue your doc skills
You may think that it’s too early to even think about joining let alone contributing to an API documentation project, especially when you’re learning. When you interact with the open-source team, you might feel intimidated that you don’t have any programming skills.
However, don’t undervalue your role as a contributor to documentation (regardless of the contribution). Open-source projects suffer greatly from bad documentation. See GitHub Survey: Open Source Is Popular, Plagued by Poor Docs and Rude People. A 2017 GitHub Survey found that
Incomplete or outdated documentation is a pervasive problem, observed by 93 percent of respondents, yet 60 percent of contributors say they rarely or never contribute to documentation.
Also check out Open source documentation is bad, but proprietary software is worse as well. The article also highlights the documentation results from the same GitHub survey:
93% of respondents gnashed their teeth over shoddy documentation but also admitted to doing virtually nothing to improve the situation. … If you think this deeply felt need for documentation would motivate more developers to pitch in and help, you’d be wrong: 60% of developers can’t be bothered to contribute documentation.
So yeah, as a technical writer, you may not be fixing bugs in the code or developing new features, but your documentation role is still highly needed and valued. You are a rare bird in the forest here.
I know the value of the doc role intimately from my own experience in contributing to open source doc projects. At one point, before focusing my energy on this API doc course, I contributed a number of tutorials in the Jekyll docs. I added instructions that included a lot of new content, and even added a Tutorials section.
I thought other developers would continue creating new tutorials in a steady stream. But they didn’t. Developers tend to add little snippets of documentation to pages — a sentence here, a paragraph there, an update here, a correction there. You will rarely find someone who writes a new article or tutorial from scratch. When there’s a new release, there often aren’t release notes — there are simply links to (cryptic) GitHub issue logs.
As such, you should feel confident about the value you can bring to an open-source project. You’re creating much-needed documentation for the project.
Enough pep talk, let’s find a project that fits your needs.
Search for an open-source project with API doc needs
To find an open-source project with API doc needs:
- Go to the GitHub Advanced Search.
- In the “With the labels” section, type
help wanted. This is a common tag teams use to attract volunteers to their project (but some teams that need help might not use it).
- Scroll to the top and notice that
label: "help wanted"automatically populates in the field. In this Advanced Search box at the top, add some additional keywords (such as
documentation) as well:
Click Search and browse the results.
Are there any projects that meet the needed criteria? If so, great. If not, adjust some of the keywords and keep looking.
If searching GitHub doesn’t yield any appropriate projects, try the following resources:
- Trending GitHub projects
- Up for Grabs
- Bus Factor
- Code Triage
- 24-hour Pull Requests
- Programmableweb.com API directory
Programmableweb.com has the largest index of API documentation projects. Many of the projects may not need documentation nor provide open-source GitHub projects for working on the documentation. However, with an index of nearly 20,000 APIs, you might be able to find a project that might align with your interests, background, and other needs.
After selecting a project, make notes on the following:
- Identify how the project tags documentation related issues.
- Identify project members who worked on previous documentation issues (which are now closed).
- Identify any currently stated documentation needs.
You don’t have to actually reach out or interact with the team yet. You’re just gathering information and analyzing documentation needs here.
Contributing will require Git skills
When you later contribute to the open-source project, you will need to understand the basic Pull request Git workflow. This might require you to ramp up on some Git tutorials a bit first, but there’s no better way to learn Git than by actively using it in a real project scenario.
Don’t worry so much about this now. You can learn these skills later when you have content you’re ready to contribute.
See the following for more information on finding an open-source project:
- How to choose (and contribute to) your first open source project
- Contribute to open-source projects through documentation
9/101 pages complete. Only 92 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.