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.
You’re probably going through this course for one or more of the following reasons:
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.
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.)
The ideal open-source API project should meet the following criteria. The project should:
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.
To find an open-source project with API doc needs:
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).
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:
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:
You don’t have to actually reach out or interact with the team yet. You’re just gathering information and analyzing documentation needs here.
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:
8/94 pages complete. Only 86 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.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson