One of the key parts of an API provider’s journey is offering documentation that contributes to a good developer experience when first encountering the API. But what should your documentation look like and how can it help potential customers through the steps of discovering your API?
One of the key parts of an API provider’s journey is offering documentation that contributes to a good developer experience when first encountering the API. But what should your documentation look like and how can it help potential customers through the steps of discovering your API? Keith Casey recently wrote a cool post breaking down the three styles of API documentation, explaining what they are and when they make the most sense to use.
Related: Best Practices and Tools for Documenting APIs
If you think of a customer’s API discovery journey as being like a funnel, you can begin to see how the different styles all play a role in helping that customer succeed. The first step is when the customer has a problem but they aren’t yet sure how it can be solved or how you, the API provider, can go about helping them. At this point, your documentation should use a Storytelling style that can speak to specific use cases and personalize them without diving too deeply into the technology and implementation details. Casey recommends that this style works best as a first pitch when you are often dealing with a less technical audience who are simply trying to figure out how to solve their problem.
The next step of the journey comes when the customer has made the decision to not only use an API, but your API. They are in effect saying “you’re the expert, show me what I need to do.” A Prescriptive style of documentation lets customers know that you understand their problem and how to solve it. Casey says that the Prescriptive style is most appropriate when customers are at the design and build phase of their project. When using this style, you can lay out good patterns and practices, and explain the tradeoffs that come with different options.
Finally, your customer has gotten past the early hurdles of using your API. They are no longer at the point of wanting to know why they should use your API, they now need to understand how to use it. This is when Descriptive style documentation makes the most sense. This style of documentation “lists every parameter, defines every term, and shows every end point. It’s 100% factual without any bias or preferences and probably written by the engineering team.”
In the end, Casey recommends that all API documentation should incorporate elements from all three styles. Storytelling should be used when the customer first comes across your API and needs to understand that it can help solve their problems. As they explore more, your docs should begin to use a Prescriptive style that lays out the patterns and practices that will help them succeed with your API. Finally when the customer is building, debugging and scaling, they are going to want Descriptive style docs that go into the details of the API.
