Kathrine Osadchenko - Measure and improve API references with use cases: challenges and best practice

”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.

Crucial use case aspects

WIX developer portal use cases

• Creates a strong and logical structure
• All endpoints in the API should be covered by main flows
• Each use case start with a summary of the user's task and introduce the flow
• Each flow should be a step-by-step: cover the entire task from beginning to end and it should correspond to the endpoints that are presented in the API
• If you have too much overlap between a few flows, try to combine them
• Try to give as much detail as you can on your side of things
• If the flow takes outside of your API, go lighter on the details, insert links to external resources
• Elaborating on some terminology might be tricky to maintain
• Include code samples if you need to

API Explorer from Adyen

• We look for a common structure in use cases: it describes what you can use it for
• Includes a full step-by-step flow and visualizes it
• This one does not have code samples, but context matters

Stripe’s use case

• Sample of structured use case - clear, definitive description of what you can do with the API
• Straightforward descriptions with steps and actions to be taken
• Ready to use code samples in different languages
• Keeps things short and sweet

"Not being able to see code is a mental block that tells a developer that this page has a lot to say and that they have a lot to do."

And that’s not all

• Endpoints alone do not answer questions about the usability and practicality of what we’re presenting
• Keep it short, concise, add comprehensive code samples
• Not being able to see code is a mental block that tells a developer that this page has a lot to say and that they have a lot to do
• The quality should be improving developer experience and success and not just to add more content to the page

Setting up the review process

1. Identify the process for your team. What comes first - API design state or development?
2. Discuss and set up how you document things - structure, applicable standards, design
3. Make ownership and dependencies clear and transparent
4. Define what to look for and include in Use cases
5. Make a review spreadsheet and use tools that work for your team to track progress and communicate

Improve your practice

• Keep open and regular communication with your team, follow up
• Look out for best practices
• Define standards that work for your API design and follow them
• Make the API review process visible for the team
• Gather user feedback and have the resources to process and address it

Takeaways

• Use cases are just one aspect of enhancing API docs
• Study what works and have resources to implement it
• Know your team, communicate to set up processes
• Know your audience and research how you can support their needs
• Treat your docs as a wholesome product