We get it, you want your API documentation to be awesome. The problem is, that documentation is hard. We are not going to sit here and say that it’s harder than building your integration, but most developers would probably want to sit down with code and data on a Monday morning rather than have to write documentation. The problem is, your developers may be the people best suited for the job. They know how it works, know how to integrate with it, and know what information other people will need to be able to utilize the API. To make sure everyone is on the same page, let’s explore some of the best practices for API documentation.
Remember Who Your Audience is
Who is your audience? Maybe you know, and then again maybe you don’t know. Who is coming to your API and needs an in-depth or even a basic understanding of how it works and how to interface with it. Are you writing only for internal developers, partners, or even enterprise customers? Make sure you have a plan in place with a good understanding of your audience before you begin.
How to Tailor Documentation To Your Audience
There are two temptations you have to fight. The first is to under-explain and the second is to over-explain. Under-explaining is an easy trap that developers fall into. They assume they are talking to someone with their knowledge base. Even when writing for internal documentation, you don’t know who will need the documentation in the future. They may not have the level of expertise or knowledge that you’d expect.
Over-explaining sounds like a good methodology especially when you are writing for external users, but people are often not coming to your documentation to read through it. They are coming to find the one or two pieces of information that they need to make things work. This means they want to find the information quickly and easily. Over-explaining everything will be tiresome for readers and make your important information all the harder to locate and find.
One method for assisting your audience that even Google uses in their documentation is to include a small section at the beginning that explains the audience your documentation was written for. Here you can list expected experiences and more. Not only will this help your audience, but it may also help give your writing focus as well.
Write What Your Audience Expects
Remember what we said about people coming to your documentation as a quick resource? This also means that your layout and the sections you include are important too. There are a few things that most developers will expect to find in the API documentation. Here are the top ten as ranked by SmartBear:
- Examples—Good examples are a great way to quickly familiarize people with how to use your API.
- Status Messages—When your API provides messages, people will be looking for answers, and that’s what your API documentation is for.
- Authentication—You want to be sure that how your API handles authentication is clearly outlined.
- Error Messages—No one likes an error, but they do like finding the cause of the error, and your documentation is the place they are going to look for those answers.
- HTTP Requests—Make sure you detail which GET and POST request types your API is utilizing.
- Parameters—What parameters does your API utilize? Make sure they are covered in your documentation.
- Getting Started Guide—A lot of these other sections can fit nicely into a simple getting started guide. Tell them how to authenticate and what they need to have a basic implementation up and running. You can always go into greater detail in further sections.
- Methods—Ensure that return values for each function or method are explained and covered.
- Code Samples—Similar to examples but this is where your users would be expected to see code in context.
- Tutorials—This is your chance to hold your users’ hands a little bit and walk them through an aspect of implementation or even the whole thing.
Include What Makes Sense
You do not have to include all of the above nor should you as some sections overlap, some sections you’ll want to combine, and there could be other sections not included above that you want to include for your specific use case. This is just a list of what people who use APIs generally expect to find. Use what makes sense, but don’t skip sections because they will be too time-consuming or work-intensive.
Unified API vs Building Your Own API
Proof for Consistency and Jargon
Read, read and reread again. Have different people read it including people that are familiar and unfamiliar with your API. We totally get it, you don’t have the time for all that. In the software world, your work needs to be done last week and your documentation needs to be in users’ hands yesterday. However, you at least want your documentation to make sense and, most importantly, you want it to be accurate.
Here are a few things you want to watch out for as you are writing and proofing. Stay consistent. Hopefully, you already stayed consistent when you built your API which will keep much of your terminology consistent from the start. Continue that into your documentation maintaining consistent and universally-accepted naming conventions and terms.
There’s a Time and a Place for Jargon
That time is when you are talking and working with your coworkers. Jargon is easy to fall into the habit of using, and that’s fine, but keep your technical jargon out of your API documentation, especially any domain-based jargon. You want to keep your language simple, direct, and as applicable as possible to a wide variety of users.
Your Documentation Is Never Done
Is work on your API ever done? Likely not. You are going to make updates and changes, improve code, and modify processes. Your API will change and your documentation will have to change too. Make sure you have a process in place to handle these updates and changes.
Without those updates, your users could encounter documentation that’s incorrect. No one likes being told to do something by documentation that either sends them down the wrong path or makes entirely no sense because your API is in a different place now than it was when your documentation was written.
Read More: Awesome API Building in Public