What makes good API docs? To answer that question and help us build the best possible developer portal for a customer, we performed a small inhouse research and reviewed existing blog posts about best practices. The following is a synthesis of what we found.
Developers know best
We figured developers would know best which factors help them in their work and which make it more difficult. That is why I collected best practices from other players in the field and conducted a quick inhouse research. While the answers for the questionnaire were pouring in, we also consulted the Internet: we checked some of our favourite API docs and tried to investigate what makes them better than others.
Some of our developers’ favourites were:
- Unity API and Manual
- Stack Overflow
- MDN SVG references
- Bootstrap
- Drupal
- Git
- Symfony
First impression
“The Drupal API docs contain everything in one place.”
All team members agreed that the first impression when they land on an API docs page is important. We found it’s best to have a separate landing page for the API docs that provides a clean visual overview that helps users immediately see where they should start their search.
Based on our background research, an ideal landing page would look something like this:
We used the table of Peter Gruenbaum as a starting point and added some additional important elements which emerged based on our research.
Your landing page should be well-structured, so that users can easily find different elements and automatically spot the one they are looking for.
Onboarding
“Actually, I’m not on a documentation page to read — I want to find a solution quickly and use it.”
There is some basic information that helps the onboarding process of new users:
- It’s good to add a Getting started section with use cases and how to’s.
- To help users understand the concept of the product, offer a reference or summary page for core concepts and best practices. Usually this section is called “Things every developer should know” or “Core concepts”.
- Make the error and warning dictionary available for users as it’s really important to provide a clear overview about this part of the API. It also provides immediate help —thus a good first impression— if developers land on your page to look for issues they just bumped into during the development process.
Visual representation
“The Unity docs are full of visual examples and it has a usable forum with questions and answers. I also like the walkthrough tutorials.”
We found out that there are some easy ways you can display information to help users:
- Break the monotony: On a tutorial page the emphasis should shift to code samples as much as possible, but they should also be paired with call outs, diagrams and highlights to break the textual monotony and emphasize important points and cool features.
- Add diagrams as most users are visual learners.
- Highlight code snippets: highlights and colours help developers spot and scroll to the part they’re interested in.
- Visualize the relations between functions and classes.
Content organization
“I don’t have time to read long manuals. I really like the UI of Stack Overflow as you can easily spot the most relevant answer based on other users’ votes.”
As you’ll probably have a large amount of content on your API documentation pages, it’s crucial to structure them logically.
- Provide example code whenever you can: for a developer a code snippet is worth a thousand words. Make sure it’s easy to copy parts or all of the code snippets.
- Example code shouldn’t be too long: it should be broken down into chunks and should only contain the essence of the code.
- Make it easily searchable: Usually the easiest way to find something in a really big project is to simply search for the concept. Make sure you know what users search for and provide relevant results.
- Cross-linking: Establish links between important content items in the description, examples and the user guide.
- Comments: Display comments right on the page they discuss or contribute to. They help clarify typical developer use cases for the code.
We hope we could get you started on planning your API documentation site. We recommend to keep testing, analyzing and improving your site — your developer community will love you for it.
