5 tips for writing better API documentation

When software moved online, so did the documentation. Today, hosted documentation is the norm. But while the formats and delivery methods for documentation have changed, the fundamental goal of explaining software has not. 

If anything, 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 larger and more diverse. 

For many users of our software, the documentation will create their first impression of our products, our people, and our brand. And nobody 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. 

That hurdle is even higher for your users who come from diverse cultural, geographic, and educational backgrounds. Creating a documentation experience that caters to all is better for inclusivity, better for your non-technical business counterparts, and better for the developer experience. The readers of software documentation today can be anyone.  

Ensuring a good documentation experience means creating an environment where anyone can easily digest your docs. That means your documentation should be devoid of jargon and should include “try it” capabilities that let people experiment, provide samples that people can use as a starting point, and include how-to information along with the actual API specs. Compelling, educational, and inclusive documentation, in turn, creates a sound developer experience that invites technologists from all backgrounds. 

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

Strive for consistency

Consistency of terminology, style, and organization are hallmarks of all good communication. It should be a principal foundation of your entire API program and the documentation process. To establish proper consistency throughout your documentation, ensure that the writing style and approach are the same throughout your team of writers. 

Enable consistency across your entire API program level by implementing a feature such as 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 developer experience and provide more comfort for all types of developers encountering your docs, regardless of their background.  

Following industry standards for your documentation, such as OpenAPI, can also help new users orient themselves quickly to a familiar pattern and establish further standardization. Clear navigation options and a consistent style improve discoverability for both features and your docs. 

Use plain language and a friendly tone

Everyone hates jargon, and let’s face it—there is a whole lot of jargon in the tech industry. Jargon not only gets in the way of clear communication but can make readers feel unwelcome. That’s the last thing you want. When writing your docs, keep the language plain and approachable, recognizing that jargon, slang, inside jokes, complicated acronyms, and the like have no place in your documentation. 

When the subject is complex, that’s when you should make your writing even simpler. It’s important to note that some users may be coming to your product with relatively little formal education. Your writing must 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 pros with little time to get the job done. Make their lives easier by providing documentation that is easy to understand. 

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

• Be alert to discriminatory language. Microsoft’s Style Guide has a concise section on bias-free communication that is a great resource.
• Use clear variable names and function names in code samples. Avoid terms that require particular familiarity to understand.
• Never assume. You don’t 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 readers of your documentation know everything. 
• Use gender-neutral terms. This should be a given. Using the second person (you, your, yours) is a great way to foster a sense of connection with your audience.
• Add alternate text to images. Remember, you want your docs to be accessible for everyone. Include alt text for all graphics and captions on video to make them visible to screen readers and other accessibility tools. 

Provide essential information for the non-technical 

Not all who look at your docs will have a developer background. Product managers, business leaders, and even colleagues from the marketing team may very well need to use your documentation at some point. 

Using easy-to-understand, real-world examples can help make technical information more easily understandable for non-technical readers. This is where “try it” or mocking capabilities (like those in Stoplight documentation) can make your documentation more useful. They can even make your API more compelling to potential customers.

For example, let’s consider the needs of a company that wants to implement a payment system for its web store. A product owner will have a general idea of the requirements. Customers need a simple, secure way to enter payment information. The business needs a way to process and track those payments. Then, payments need to turn into orders that must be fulfilled.

The product owner may be the first person to look at the API documentation for the payment system. They may want to evaluate multiple APIs at a high level before asking a developer to do an in-depth analysis of those that would best fulfill the company’s needs. In this case, the API with the best documentation will stand a better chance of coming out ahead. Just remember, the person consuming your documentation won’t necessarily come from a developer background. 

Take a design-first approach

At Stoplight, we take a design-first approach to all that 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 designing your documentation. Your API documentation needs to meet users where they are and speak to their needs. It needs to be more than a list of endpoints and methods. 

Thinking about 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 writing your docs, write for every use case. As you draft your docs, the traditional developer, the non-traditional developer, the business counterpart, possible partners, and the end consumer perspectives should all be kept in mind.

Get creative with multimedia

If you aim to make your docs more engaging and inclusive, always try to find ways to showcase hands-on guides to implementation. Get creative, highlight use cases from diverse companies and developers, and provide sample apps and technical manuals based on real-world scenarios. Take advantage of multimedia like videos, graphics, or gifs to make your docs more enticing and cater to those who may absorb information more easily in a format other than strictly text. 

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

As a final thought, writing for all is not about lowering expectations but about broadening them. Writing more accessible documentation will result in more people testing out your product and coming back for more. Clearly written and broadly accessible documentation results in more productive developers, longer-term users, deeper integrations, and stronger brand affinity. 

For more resources on how to write good documentation, check out this best practices guide.

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

—

New Tech Forum provides a venue to explore and discuss emerging enterprise technology in unprecedented depth and breadth. The selection is subjective, based on our pick of the technologies we believe to be important and of greatest interest to InfoWorld readers. InfoWorld does not accept marketing collateral for publication and reserves the right to edit all contributed content. Send all inquiries to newtechforum@infoworld.com.