Best practices for API documentation -- podcast with Andrya Feinberg
I recently talked with Andrya Feinberg, a documentation manager and content strategist for Emotient, about best practices with API documentation. Below is a writeup Andrya has provided that summarizes some of the points she makes in the podcast.
Listen here:
Here is Andrya's summary of the best practices:
API Documentation Best Practices, by Andrya Feinberg
In the world of Technical Communication, Content Strategy, User Assistance, Information Architecture, and User Experience, there have always been best practices and industry standards. Each type of content, independent of which industry you are in, has its own set of rules, a style guide, and a terminology usage guide.
I live and breathe best practices and industry standards. Why? This is what helps me to create content that is easy to use, easy to read, easy to understand, and minimal. There's nothing more appealing than content that is simple, clean, and gives you exactly what you want.
When I created my survey on API documentation, I put myself in the user's shoes, as we should always do, and I wanted to make sure that I performed an exhaustive audience analysis.
Why would I put myself in the user's shoes and create content solely focused on the user's needs? Creating content for a specific user is what it's all about, and I can't emphasize this enough. It's my passion and my purpose. People don't have time to read through a sea of text to find the information they need. We are in a hurry and have a task in mind. At that exact time, we must find exactly what we're looking for. If we don't, we are left irritated and frustrated and must go somewhere else to find the answer.
I know that if I have to spend more than two minutes looking for what I need, I get a tad bit irritated. Okay, probably more than a tad, but you get the idea.
Every user has expectations, and it is the technical communicator's purpose and goal to not only meet the user's expectations but to exceed them. Make this your priority and your focus, and your users will thank you over and over again.
Here are the best practices for API documentation. These came directly from the responses that I received from engineers and developers that spend their lives in APIs with API documentation.
Create content that is easy to use, read, and understand.
- Create an exhaustive and concise plan for API documentation.
- Make sure that you talk to all of your SMEs, engineers, and developers to create what they need and what they want.
- Keep related topics together.
- Focus on how you can provide the right information to the right user at the right time.
Make sure that the content is consistent and accurate.
- Don't leave anything out, such as missing segments or examples of code. This is all levels of wrong! Leaving out part of a command or a call leaves users frustrated and irritated. What's worse is that they can't use (and don't trust) the API!
- Make sure that the documentation reflects the way that the API works.
Include an 'overview' or an 'introduction'
- Put this at the very beginning. Think of this as the 'landing page'. The most difficult part of adopting an API is at the beginning. If there is a learning curve, or if the developer is new to the programming language, this makes the content in the introduction even more critical to their success!
- Make this 'minimalistic' (think simple, easy, minimal steps) that provides developers with how to use this API.
- Include only the essential, critical information that developers need to know. The rest of your documentation will include the details or specifics of these items and more advanced concepts.
- Include information about the architecture and 'why' the developer should use this API.
- Make it easy for a developer to get started!
Make it easy to scan.
- Make this a single, long page document with hyperlinks. Don't go overboard on the hyperlinks. This just gets too messy and shows that you haven't organized the information clearly for the user.
- Make sure that the hyperlinks work. There's nothing worse than clicking a link, and you get an error.
- Keep related topics together.
- Provide examples. This reduces the time developers spend learning and implementing the product. It also enables developers to make a call quickly and easily.
Make it clean, simple, and minimal.
- Make it minimal. The most important piece of information isn't the home page, the sign-up page, or other pages on the website. It's the API documentation.
- Make it simple. API documentation is core to the user experience.
- Make it simple. Yes, I said it again, because it really is that important.
Focus on tasks.
- Focus on tasks. Yes, this is redundant, but I can't emphasize this enough.
Emphasize code samples.
- Provide as many API code samples as possible.
- Make sure that the code samples are accurate. This removes the ambiguity when the developer implements a call.
You can contact Andrya with any questions you may have.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.