5 Tips for Writing Better API Documentation

When the software went live, so did the documentation. Today, hosted documentation is the norm. But while documentation formats and delivery methods have changed, the fundamental purpose of explaining software has not changed.

On the contrary, writing good documentation has become more difficult in recent years. The complexity of the information needed to support software products has increased dramatically. At the same time, the audience for documentation has grown and diversified.

For many users of our software, the documentation will create their first impression of our products, our people and our brand. And no one likes poorly written documentation. I think we can all recount at least one experience where insufficient documentation turned us away from a product, and we never looked back.

This hurdle is even greater for your users who come from diverse cultural, geographic, and educational backgrounds. Creating a documentation experience that appeals to everyone is better for inclusiveness, better for your non-technical business counterparts, and better for the developer experience. Readers of software documentation today can be anyone.

Ensuring a good documentation experience means creating an environment where everyone can easily digest your documents. This means that your documentation should be jargon-free and should include “try it” features that allow users to experiment, provide examples that users can use as a starting point, and include how-to information as well as the actual API specifications. Compelling, educational, and inclusive documentation, in turn, creates a sound development experience that invites technologists from all walks of life.

Here are five tips to improve your API documentation for every user, but especially to help users from non-traditional backgrounds.

Look for consistency

Consistency of terminology, style and organization are hallmarks of good communication. This should be the main basis for your entire API program and documentation process. To establish consistency across all of your documentation, make sure the writing style and approach is the same across your team of writers.

Enable consistency across your entire API program by implementing functionality like API style guides to help you govern and maintain consistency across the group. Focus on practical, predictable organization and consistent offerings throughout your documentation to create a better development experience and provide more convenience for all types of developers encountering your documents, regardless of their background.

Adhering to industry standards for your documentation, such as OpenAPI, can also help new users navigate a familiar pattern quickly and establish further standardization. Clear navigation options and a consistent style improve visibility of features and your documents.

Use plain language and a friendly tone

Everyone hates jargon, and let’s face it, there’s a lot of jargon in the tech industry. Not only does jargon get in the way of clear communication, it can also make readers feel unwelcome. It’s the last thing you want. When writing your documents, keep language simple and accessible, recognizing that jargon, slang, inside jokes, complicated acronyms, etc. have no place in your documentation.

When the subject matter is complex, that’s when you need to make your writing even simpler. It is important to note that some users may gain access to your product with relatively little formal education. Your writing should be accessible to the full spectrum of possible users, from self-taught developers, non-native English speakers, and developers fresh out of college to experienced professionals with little time to get the job done. Make their life easier by providing easy-to-understand documentation.

Here are a few other things to look out for when striving for an inclusive tone and clear language in your documentation:

  • Be aware of discriminatory language. Microsoft’s style guide has a concise section on unbiased communication which is a great resource.
  • Use clear variable names and function names in code examples. Avoid terms that require special familiarity to understand.
  • Never assume. You do not need to include a detailed discussion of every concept in every document. Link to another source with a definition or in-depth discussion when you don’t have the time or space to explain it in context. Don’t assume that the readers of your documentation know everything.
  • Use gender-neutral terms. It should be a given. Using second person (you, your, yours) is a great way to foster a sense of connection with your audience.
  • Add alt text to images. Remember that you want your documents to be accessible to everyone. Include alt text for all graphics and captions in the video to make them visible to screen readers and other accessibility tools.

Provide essential information for the non-technical

Not everyone who views your documents has developer training. Product managers, business leaders, and even marketing team colleagues may very well need to use your documentation at some point.

Using concrete examples that are easy to understand can help make technical information more easily understood for non-technical readers. This is where “trying it out” or simulation capabilities (like those in Stoplight documentation) can make your documentation more useful. They can even make your API more appealing to potential customers.

For example, consider the needs of a company that wants to implement a payment system for its online store. A product owner will have a general idea of ​​the requirements. Customers need an easy and secure way to enter payment information. The business needs a way to process and track these payments. Then the payments need to turn into orders that need to be fulfilled.

The product owner can be the first person to view the API documentation for the payment system. They may want to evaluate several APIs at a high level before asking a developer to do an in-depth analysis of which ones would best meet business needs. In this case, the API with the better documentation will have a better chance of coming out on top. Remember that the person viewing your documentation will not necessarily come from a development background.

Take a Design-Driven Approach

At Stoplight, we take a design-driven approach to everything we do. This means focusing on building APIs for the humans behind them and considering all stakeholders who may interact with, create or consume the API. This same approach can be applied to the design of your documentation. Your API documentation should meet users where they are and meet their needs. It should be more than a list of endpoints and methods.

Viewing your potential users as a diverse group with different goals can help you organize your documentation to inspire creativity and reflect the real world. When you write your documents, write for each use case. When drafting your materials, you need to keep in mind the perspective of the traditional developer, the non-traditional developer, the commercial counterpart, potential partners, and the end consumer.

Be creative with multimedia

If you want to make your materials more engaging and inclusive, always try to find ways to present how-to implementation guides. Get creative, highlight use cases from various companies and developers, and provide sample applications and technical manuals based on real-world scenarios. Take advantage of multimedia like videos, graphics or gifs to make your documents more engaging and meet the needs of those who can more easily assimilate information in a format other than strictly textual.

This old adage that “treat others as you want to be treated” applies to readers of your documentation. Write how you would like someone to explain something to you, taking into account the variety of people and backgrounds that your material may come across. Empathy for the developer and the user is the main way to work towards a better end-to-end experience for developers and users.

In conclusion, writing for all is not about lowering expectations but about expanding them. Writing more accessible documentation will encourage more people to test your product and come back for more. Clearly written and widely accessible documentation translates to more productive developers, longer-term users, deeper integrations, and stronger brand affinity.

For more resources on writing good documentation, check out this best practices guide.

Pam Goodrich is a technical writer and documentation strategist at Stoplight.

The New Tech Forum provides a venue to explore and discuss emerging enterprise technologies with unprecedented depth and breadth. The selection is subjective, based on our selection of the technologies that we think are important and most interesting for InfoWorld readers. InfoWorld does not accept marketing materials for publication and reserves the right to edit all contributed content. Send all inquiries to [email protected]

Copyright © 2022 IDG Communications, Inc.

Sam D. Gomez