Creating brilliant API documentation can be tricky. It’s something of a balancing act: curating the essential information developers need to get started quickly, while still fleshing out other, more complicated topics in detail. But what if you could improve the developer experience for users across the board with just a few simple tweaks?
Inspired by some of Stripe’s latest additions to their documentation, we’ve come up with a list of 8 of the tiniest tweaks for your API docs that are guaranteed to deliver big on developer experience! From an eyesight-friendly dark mode to a humble table of contents, here are some small changes that give API documentation a special edge.
1. Dark Mode
Dark mode, also called night mode, has been making a comeback in recent years. Whether we should be thanking the nostalgia of eighties computer interfaces or the growing numbers of midnight Reddit users, dark mode is slowly becoming an expectation. Recent studies have even suggested that dark mode interfaces use less power and feel easier on the eyes.
In any case, dark mode is a straightforward feature you can add to your API docs. Some developers will love it just for the cosmetics, while others will quickly find themselves building new integrations under the moonlight, thanks to the improved visibility.
2. Rate This Page
Another trending feature on support pages of all types — not just API docs — is the ability to rate the page. The Shopify docs ask “How helpful was this page?”, allowing you to respond on a five-point scale from a smile to frown, while Stripe asks the binary question “Was this section helpful?”
However you choose to implement it, an essential rating feature is an easy way to improve the developer experience. Of course, having a rating widget on each page (or section) is only half of it: you also need to revisit and revise the pages based on developers’ feedback.
3. Instant Load
It’s the 21st century and speed is more important than ever. There’s nothing more frustrating than a page which takes several seconds to load, especially when you’re scanning through dozens of them at a time, looking to find an ultra-specific tidbit.
Do your developers a favor and have pages optimized for quick load speeds! Stripe now boasts “instant load” on its docs pages, but we certainly won’t complain if your pages take a few tenths of a second. With simple measures like caching and image optimization, reducing page load times is easier than you think.
4. Status Widget
In our recent article on 5 Examples of Great API Documentation, we praised GitHub for the simple API status widget they feature on every page. Although this particular feature might be a little more involved in terms of implementation, it’s a fantastic time-saver in those rare circumstances when your API is in for maintenance, or otherwise topples over.
5. Featured Topics
The “Featured Topics” or “Popular Topics” section is a tiny tweak we picked up from the Google Maps Platform Documentation. You’ll find that a lot of developers land on your documentation homepage — whether it’s through search or by referral — and this is an excellent opportunity for you to nudge them in the right direction.
If used correctly, a “Featured Topics” section guides developers towards the information they’re most likely looking to find. Alternatively, you can use this feature to promote new or under-appreciated features, which would otherwise be overlooked.
6. Click to Copy
Click to Copy is a feature I’ve seen on both Stripe and Twilio reference documentation. It’s exactly what it sounds like: a button you can click to copy a code snippet automatically. Sure, it might only save half a second of your developers’ time, but every little bit counts, especially when developers are copying things a multitude of times!
7. Table of Contents
A table of contents is a simple addition to each page of your documentation. Once again, this helps save developers’ time, time and time again. Over at the Shopify docs, they include an “On this page” section with hyperlinks to the page’s two to five parts.
There are no set rules on how you should implement this. Whether you choose to include a table of contents on every single page or just some of them, for example, is up to you. In any case, the end goal is to get developers to the information they need faster.
8. What’s Next?
What’s Next? is yet another feature we pruned from the Twilio Docs. You can assume that developers reading your documentation are following a progression — perhaps implementing your API for the first time — and, based on that, you can offer suggestions for what they should read next in the form of a What’s Next? section.
For example, if you start on Twilio’s Sending Messages page, you’ll eventually be recommended the documentation to “turn your messages into a conversation,” “track the delivery status of messages,” or “optimize your message deliverability.” These are all relevant suggestions, and you can bet that a handful of developers click through to them!
There you have it: eight tiny tweaks for your API docs which deliver big on developer experience. Sure, some of these are more effective than others, but we’ve sourced every single one of these directly from the world’s biggest and best documentation. You can bet that if you implement these same features in your reference docs, developers will have only good things to say about the changes!