”A good API thinks through its developer experience, providing complete, accurate, and easy-to digest documentation and references. In other words, API docs should help developers by thinking through common use cases, the sort of real-life scenarios that users of the API want."
Apply use cases for APIs to drive product usability without creating a mental block for devs
It’s an opportunity to get diverse teams involved in shaping the developer experience
It’s important to approach API design reviews in a methodical, well thought-out way
Bringing yourself into the project management mindset as a technical writer can give you extra leverage, whenever you are trying to interact with other teams
Where to start
Think of what your API users will ask when they see the final docs:
Do I need this API?
What is it for?
What can it do for me?
Where do I start?
Widen your horizons and check how other well-established devportals present their structure and their API references and see what works in the context of your product and audience.
What to address
What are the possible biases?
Structure: does it make sense and is it easy to navigate?
Are code samples up to date and reusable?
Is there a clear purpose for the API reference?
What would be the challenges in adding content to our APIs?
What can we do about it?
Bring a TW on board early to get a 3rd party perspective
Set up a review process to address questions and track progress
Over-communicate with the dev team for any technical and structural updates
Measure what works with use cases
If we want the API to work aka be used, integrated, expanded, we can benefit from thinking of it as a product of its own that has its own use cases.
Provide examples or real-life scenarios of what actually happens when you use the API, showcase the flow and possible outcomes.