3 Easy Ways to Improve Your API Documentation

Developers use APIs every day.

In fact, some are spending a majority of their work week on APIs, not only using them, but performing research, trying them out, and digging into documentation.

It’s more important than ever to have great documentation that helps all developers access and use your APIs.

So here are 3 ways to start improving your API documentation experience today.

Actually Read Your Docs

This might seem like a simple (and groan-worthy) suggestion, but actually take the time to read your API documentation, especially if you use an automatic documentation tool like Stoplight Elements.

The tool will do most of the work, but a human eye can help improve your consumers’ experience. After all, people read and use the documentation, not computers.

Focus on Accessibility

The World Health Organization has estimated that 15% of the world requires specifically accessible content. And a recent Stack Overflow developer survey found that 3.4 percent of respondents identified that they have a disability.

When API documentation is created with accessible components, it improves the overall experience for all consumers, leading to higher adoption for your APIs.

First, take time to educate your team about accessibility requirements. Work with your team to ensure your API documentation is usable by screen readers, that colors, images, and tables also include labels and alt text, and that your documentation includes white space for easy scannability and navigation.

Finally, use an ADA compliance automated tool to check the outcome.

accessibleweb.com/website-accessibility-checker

Try the New API Documentation Experience in Stoplight Platform

One of the easiest ways to improve your API documentation is to try out the new Docs experience in Stoplight Platform.

Powered by Elements, we’ve added new features and enhancements to make your docs more beautiful, readable, and accessible.

• Improved Designs: we’ve refreshed Typography, Code Blocks, Callouts, Tabs, Tables to be easier to read, consume, and access
• New Code Groups: Sequential code blocks now convert automatically into a tabbed code group. This feature is great for multi-language code samples.
• Mermaid Diagrams: Use the Mermaid code block language to automatically render diagrams. Show off powerful API features and workflows in easy to understand diagrams.
• Product Images: Add an image annotation with the focus property to render the image with styling that’s great for highlighting product images. Also supports custom background colors (bg).
• Images: The title property will now be used to display a caption, which will help with screen reader useability and web crawling.