7 Tips for Writing Better API Documentation

Sharing is Caring

If an API isn’t documented, the chance of it being consumed by other developers is incredibly low. For a very long time, companies like Microsoft, Salesforce, and Apple were dominant players in technology. They were dominant players because they had a compelling product and great documentation.

Tip 1: Be consistent

The hallmarks of great communication are terminology, style and organization. The writing style and approach should always be consistent. Develop a style guide if you need to.

Besides having great documentation, the API needs to be intuitive and follow conventions. If you are creating a REST API make sure to read the article 5 Best Practices for Designing RESTful APIs.

Tip 2: Write Documentation for your audience

When writing documentation there are likely two groups of people that might like at it: business folks, and technology folks.

The technology folks will need features like examples and documentation on the acceptable data types. Technology folks will also need to see a lot more details about when errors occur.

The business folks will want easy to understand real world examples or use cases. The business folks are the people that normally have the purse strings.

Your own business folks are likely to read the documentation whether they be in sales or marketing.

Tip 3: Organize your documentation

Documentation should be organized by using heading, summaries and examples. People do not generally read entire documents when they need to try and do something – they often skim read until they find what they think they need.

Headings and Summaries allow us to “skim read” more efficiently.

Tip 4: Avoid Jargon

Avoid jargon and use plain language unless your API is specific to only one business domain.

Jargon usually gets in the way of communication and makes people feel unwelcome. Welcoming documentation uses simple and plain words, and no acronyms.

Tip 5: Automatically Generate Documentation (Swagger, Open API, etc)

API documentation when it is manually created is often very out of data and requires a lot of effort to keep it aligned. It’s usually best to try and automate it and use something like Swagger/OpenAPI. If your API is built in Node.js have a look at the swagger-jsdoc module.

Swagger/OpenAPI is the leading documentation solution for APIs. There’s a bunch of reasons:

  • Great user experience: documentation is interactive and can build CURL requests. Can even build and generate a request and see the results in the Swagger UI.
  • It’s machine readable, so it can be potentially automated. 😊
  • Open source, free to use. Free as in freedom and free beer.

Tip 6: Make the Documentation Publicly Accessible

Nobody enjoys using API documentation that is hidden behind password protected pages and impossible to find with Google.

Tip 7: Assume Nothing

Assumptions are frequently wrong. If you need to have knowledge of something, provide a link or explanation to the details. I don’t know everything and neither will your readers.

As I was told frequently in the army, Assumptions Make an Ass out of you and me.

Sharing is Caring

Brian is a software architect and technology leader living in Niagara Falls with 13+ years of development experience. He is passionate about automation, business process re-engineering, and building a better tomorrow.

Brian is a proud father of four: two boys, and two girls and has been happily married to Crystal for more than ten years. From time to time, Brian may post about his faith, his family, and definitely about technology.