Where the Wild Docs Are
Where should open source documentation live? README or on a static site?
Aug 8, 2019
Every developer deserves a good experience working with any API. They expect an accurate reference and some sample code to get started. However, there isn’t a single checklist of what developers need. APIs won’t always have the same audience and your documentation should reflect the most common consumers. Everything these days is tailor-made to resonate with a specific audience. Why should your API documentation be any different?
Let’s explore how documentation should change according to different developer audiences. Ultimately, whether you’re talking to your internal team, communicating with partners, or speaking to developers at large, your API needs clear documentation that speaks to their individual needs.
Internal use is not an excuse to provide poor documentation. In fact, your APIs should increase team efficiency. However, your colleagues come to your API with a lot of knowledge about internal projects and access to tooling you may not be able to expose to external developers. Your documentation should connect the dots.
Documentation for your team, or company at large, should first answer some basic questions: What need does this API fill and who is it for? What business goal is it helping to achieve? The technical information is important, but giving proper context on the purpose of the API is helpful for team members to get excited about it, and understand how it can be used to better serve internal and external stakeholders.
Assuming some of this audience is already familiar with your API, this documentation can be less tutorial in nature, and include use cases of how it’s being used within the company as a jumping off point for learning. Sharing code samples is also a great way to explore functionality and possibilities.
Are there ways to bring the documentation to life for your internal audience? Creating tutorial videos, offering code review sessions, and setting up a Slack channel for questions are a few easy ways to bring the API to life for your fellow teammates and co-workers.
APIs not only increase efficiency internally, but they also make it easier to form partnerships with other companies. Some partners may approach you and others may be targets of your business development team. In either case, the developer experience greases the wheels of both the technical and business sides of an integration.
Effective documentation is crucial for a partner who intends to use your API to benefit their business. Let’s face it: if your API has subpar documentation, developers from a partner aren’t likely to implement it in their code, especially since they can’t walk down the hall or hop into a quick chat for help from the person who created it. In fact, poor documentation could potentially kill a deal when the partner’s engineer provides a negative review or outrageous estimate of what it would take to integrate.
In addition to an excellent API reference, you want to help the partner envision why the integration would be successful. Provide context on how to use the API based on the partner’s industry, and cite use cases of how it’s being used by others. What problem did your API solve for a partner in the past? Include a case study about it in your documentation to get developers inspired! This practical, easy-to-implement type of documentation also enables sales and marketing to spread the word to potential partners about your great work.
Lastly, you’ll have to decide whether to make your partner API documentation public. Security is the most common reason companies choose to keep docs private. However, just because anyone can find your docs does not mean they’ll have access. Public documentation helps partners easily share internally and may help new partners discover what’s possible before any formal discussion takes place.
There’s no question about where the documentation should live for public developers. A complete portal with all types of API documentation is a prerequisite to a public API program. The expectations from this audience will be high but the payoff for getting the developer experience right is invaluable. It can amplify awareness for your API, including key partners.
These curious, hungry developers will ultimately be your biggest cheerleaders if they like your API, and by proxy, your API documentation. This audience is most likely to recommend your API to their followers and the companies they work for. They see a lot of documentation and most of it is bad. You can help them sing your praises with a clear reference and supporting docs that speak to both the power and ease of the API.
Use quickstart tutorials to get them to initial success. Provide practical use cases, small and large, of outside developers using your API to achieve various goals. If possible, point to complete sample apps for these use cases. This audience is savvy and innovative. They want approachable, technical guides, not marketing speak.
Your ultimate goal with documentation aimed at this audience, is to teach developers to use your API so they can better rely on, or extend, your product or service. In addition to tutorials and guides, help bring developers closer with API testing functionality. The easier you make it to test, play and learn, the more likely they’re going to use your API to improve their experience with your product or service.
Ultimately, good API documentation has a lot in common: it’s inclusive, human-friendly, easily discoverable, and curious in nature. But great API documentation is written with a specific audience in mind. Whether you’re talking to an internal team, a partner, or a long tail developer, write documentation that speaks to their particular needs and sparks inspiration in all.