Activity: Find an open-source project
To break into API documentation, you need to start thinking about API documentation samples in your portfolio. Your portfolio is key to Getting an API documentation job and thriving. Without a portfolio that contains compelling API documentation samples, it will be tough to get a job in API documentation.
- Avoiding a catch-22
- Finding an open-source API project
- Activity: Find an open-source project with API doc needs
- Recognizing the type of API used in the project
- Contributing will require Git skills
- Don’t undervalue your doc skills
- More reading
- Next steps
Avoiding a catch-22
Let’s assume you don’t have any experience in API documentation, but you’re trying to get an API documentation job. Employers will be willing to overlook experience if you can demonstrate API documentation writing samples. But how will you get API doc writing samples without an API doc job? And without API doc samples, how can you get an API doc job? This can seem like an impossible situation.
Getting around this catch-22 is simple: you create these API doc samples through open-source projects that you contribute to. This is where the activities in this course become essential.
Rather than merely completing modules and tracking your progress toward the course’s completion, the activities you do will help build up your portfolio with API documentation samples, helping you progress to the goal of either obtaining an API documentation 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 so common, GitHub provides advice for finding open-source projects.)
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.
Activity: Find an open-source project with API doc needs
To find an open-source project with API doc needs:
- Go to the GitHub Advanced Search.
-
Under the Issues Options section, in the With the labels row, type
help wanted. This is a standard tag that 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
API documentation) as well:
-
Click Search and browse the results.
In the results, you might want to look for a REST API project (rather than a native-library API such as a Java API). Developers don’t often distinguish between the two with requests related to API documentation. If you see doc requests related to Java, C++, JavaScript, or some other programming-specific framework (with no identifiable endpoints), it’s probably not a REST API. However, working on such a project could be equally fulfilling as a learning opportunity. It depends on what you’re interested in.
As you browse the results, are there any projects that look interesting or promising? 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
- Crowdforge
- Up for Grabs
- Bus Factor
- Code Triage
- Changelog
- 24-hour Pull Requests
Note: You could spend a long time evaluating and deciding on open-source projects. For this activity, it’s okay if you focus on a project that looks only mildly interesting. You don’t need to commit to it. You can always change it later. -
After selecting a project, make notes on the following:
- Does the project involve a REST API?
- How does the project tag documentation-related issues? For example, does it use the “documentation” label?
- Identify the current state of the project’s documentation. Are the docs robust, skimpy, nonexistent, extensive?
- How active is the project? (What is the frequency of commits?)
- How many contributors does the project have?
You don’t have to actually reach out or interact with the team yet. You’re just gathering information and analyzing documentation needs here.
Recognizing the type of API used in the project
When you look for API projects, recognize that there are many different types of APIs. Many of the APIs you run across might be native library APIs, which don’t use web protocols to make requests and responses (as REST APIs do) but rather involve incorporating a language-specific library into the project. If the API seems to focus on a particular language, and the API documentation looks auto-generated, it’s probably a native-library API.
