Starting with API Documentation — Leveraging Your Developer Experience (DX)
This article is part of the Leveraging Your Developer Experience (DX) series. Find out the rest of the content here.
Documentation is a critical component of your developer experience.
When trying to improve your developer conversion rate and/or promoter score, working on an high performing/ accurate and easy-to-implement API is the first lever you must take into account.
Developers respect clean, simple code. It also applies to documentation.
Be reliable
Developer experience will always start with providing a reliable API that teams will want to work with, and can trust to securely integrate with.
Documentation is the interface agreement you entertain with your developers base. To be reliable and trustworthy, your documentation must reflect the reality of their usage over the time, meaning:
- Documentation should be as descriptive as possible. It may include technical writing, code samples but also conditions of use such as rate limiting or error management (that is very often not present at all).
- Information must be accurate, all parameters description for example must be introduced in a structured way and as rich as possible. Avoid typos!
- Documentation must be maintained over time. Each new feature/ property as well as deprecation of services must be documented and anticipated because it may impact directly the agreement you have tied with your developers. Make sure you are not breaking stuffs!
- Ensure that documented operations are working properly (i.e. in a performant and usable way).
API should be marketed as one of your product offer in your website. Therefore you must provide visibility and accessibility to the documentation. It means do not hide API documentation but in the contrary work on a dedicated developer environment highlighted on your main marketing website in the header or the footer.
Building your API documentation journey
Today, some of the most well-known and widely adopted APIs are investing in rich, human friendly documentation for their APIs. Companies like Twilio, Stripe or the French player Algolia have invested a significant lump of money and energy in their documentation — that’s a strategic move in building a strong brand among developers.
If you are working on your API documentation project, please read the next article for tip 1: What documentation gimmicks should I play with?
