When RESTful APIs first hit the radar, one of the benefits often cited was that the APIs could be easily understood from the WADL alone. As the industry evolves and APIs become more central to the software development process, both providers and consumers have started to recognize the need for better, more easily consumed documentation.
Hence the rise of API description formats like Swagger, API Blueprint, RAML, etc… but here’s an interesting trend that started to take shape in 2015… the rise of the API technical writer. According to the Bureau of Labor Statistics, “Employment of technical writers is projected to grow 10 percent from 2014 to 2024, faster than the average for all occupations. Employment growth will be driven by the continuing expansion of scientific and technical products and by growth in Web-based product support. Job opportunities, especially for applicants with technical skills, are expected to be good.”
So what is the difference between good API documentation and GREAT API documentation? While this continues to be a bit of a debate, we are seeing certain trends emerging, both in consumer expectations and producer implementation.
Technical Content – how much is enough?
As we already mentioned, we’ve moved past the assumption that an API description file is enough for your consumers. Interacting with API often involves more than just understanding the methods and resources.
It’s important to explain the authentication model you’ve incorporated into your API and why you chose it. Make sure it’s easy for a developer to not only get their client token, but understand how to refresh it and any restrictions that apply.
For example, if you use OAuth, be explicit about whether you are using two-legged or three-legged OAuth, and provide flow diagrams to lay out exactly how your authorization flow works. This can be the trickiest part of API implementation for most developers and having a technical writer architect this information can be invaluable.
Many developers jump straight from API description to sample code, with no stops in between. They want to see how easy it is to implement your API and also play with what they are most familiar with, which is (of course) code. Incorporating the sample code into your documentation gives them context for the code snippets and a way to research any issues they might encounter. And don’t forget, not everyone loves Python the way you do – give choices and encourage feedback on what’s missing. If you provide code samples in the 4-5 most widely used languages, that’s a good starting point and can satisfy the majority of your audience. But be prepared to keep current – this is one of those areas where you have to keep an eye on emerging trends to be sure that the code samples you include are still relevant to most developers.
Once you accept that the API description file isn’t really the complete set of documentation for your API, you need to decide what you will include in the reference documentation. Again, most developers just want to get started coding so make sure that information is front and center:
- Hello World
This should ideally provide enough detailed instructions for a developer to make a call and get a response from your API.
While having a high-level overview of your authentication model is important, it’s equally important to provide specific instructions for authenticating against your API.
- Using the Endpoints
Describing the capability exposed by each endpoint is a start but round that out by providing sample calls and responses so the consumer knows exactly what to expect from each endpoint included in your API.
- Trying it Out
Good API documentation not only describes how the API functions but also encourages experimentation. If you have a sandbox, provide detailed information about how to use it, including getting credentials and using the test data. And don’t forget to provide cURL commands for developers who want to quickly make a call and see the response payload.
- Error Codes
Include information about each error they might hit and how to resolve the issue. In fact, in my company, we’ve established a requirement for including a link to this documentation in the error message structure itself. Also make sure they know what they can do for their end-users when this error is encountered – can they provide a user-facing message of their own?
- How to get help
This is just pure Documentation 101. Make sure your users always know how to get additional help if they can’t get the answers from your documentation.
Marketing Content for your API
If your organization has both technical writers AND marketing writers, you are living in the happiest of worlds. Often, the writer needs to wear two hats and provide both types of content. They’re both important! Good marketing copy is what brings people to your doorstep. If you want developers to take a closer look and give your API a try, you need to make sure they first know:
- Your key features and the problems they solve.
- Some standard use cases for incorporating your API into an application
- What your usage requirements are
- How often you will release updates and how they can find out about them
Don’t underestimate the power of good technical marketing content. Ideally the marketing content flows easily into the technical content, with the same voice and target personas.
Let’s face it – not everybody reads the reference documentation. Some people will try out the API, hopefully using your sample code and cURL commands, then jump immediately to your support forums or FAQs to get more information. Having a technical writer who can provide content in those areas ensures that the reference documentation includes the right information and gives you an opportunity to link the support information back to the reference docs.
Great documentation helps everyone
In the end, you and your consumers want the same thing: success with your API. You can help accomplish this by providing clear, simple, and complete information that provides the kind of information developers can trust and, maybe more importantly, use immediately.