7 Unconventional Opportunities to Improve Your API Documentation When developers think of documentation, we often tend to think of walls of texts or verbose reference guides. However, the purpose of documentation is to be the UI layer for an API or code library: when you’re learning something new, documentation is the frontend that you spend most of your time interacting with. At ReadMe, we’re trying to get away from walls of text. To us, “documentation” is an umbrella that covers anything that gets you closer to understanding the tools you’re using. Sometimes, that means writing a few paragraphs of text. However, more often than not, English isn’t the best way to transfer an understanding of what’s going on. Code is so precise and logical, yet we share the knowledge using the notoriously ambiguous English language. So, here are seven things that don’t seem like documentation… but actually are: Support forums Documentation should be cohesive, like a story. You need to cut the unimportant parts, and make sure it flows properly. Otherwise, your documentation will be thousands of pages long and completely unapproachable. However, APIs and code libraries have so many edge cases and alternative use cases, it’s impossible to succinctly wrap it all up. Support forums can be your untamed frontier that fills in the gaps. There doesn’t have to be any structure, and there’s no limit to the number of questions/answers you can host. Who cares if there’s thousands? It’s not like anyone is going to sit down and read them start-to-finish. You and your users can just throw in questions and answers around willy-nilly, and those questions can be surfaced by search. Dashboards Quite often, documentation will bounce you to the “dashboard” to get your API key. It’s crazy that documentation and dashboards are separate. The dashboard is where all the information about the user and the app lives. It’s insane that dashboards (info about the user) and documentation (info about the API) are in their own silos. Imagine how much more proactive documentation could be if it knew about the user? (Of course, if you don’t want to imagine, you can read a bit about our Getting Started pages, or see for yourself what they’re like on the user end.) Onboarding The goal of onboarding a new user shouldn’t just be to get them their API key. It should be to get them to the Minimum Viable Call. Your API probably does hundreds of things, but we want to get the user set up and running the most boiled down, basic call possible. For Twilio, it’s sending a text message. For Facebook, maybe it’s getting your own profile. The MVC shows the user that everything is set up successfully, and gets them started using your project. Use the onboarding process to gather as much information as you can (API key, programming language, etc), and then show them a customized copy-and-pasteable code snippet in their language with their API key. Interactive playgrounds If a picture is worth a thousand words, a one-click “try it now” button is worth a million. Rather than making users fire up their text editor, start a new project, and get everything integrated before they can make a call, we should be letting them do it instantly. This lets people tweak and play around, and see exactly what they’re going to get back. No longer do you have to write a bunch about error codes and what will be returned and what is required… just let people tweak the examples and try it for themselves. And, after they’re done tweaking, provide them with a copy and paste-able code snippet. Error messages Error messages are a great place to include documentation. Almost nobody proactively reads documentation about errors, and when they get one, they Google it. We can use error messages to surface actual documentation. My favorite (non-ReadMe) example is AngularJS. Not only does it link to the relevant doc in every single error, it takes it a step further. The link includes your actual stack trace and variables. So, the AngularJS page is half static documentation, but half the actual error you’re having. So, no longer does it say “one of your variables”… it actually says “your variable ‘test’ isn’t working” or whatever. Here’s an example. (Note the page includes the actual stack trace that brought me to the page.) SDKs There’s a ton of debate on whether SDKs are a good idea. Many API purists believe that everything should be a URL, since it’s a common interface that everyone understands. However, SDKs undeniably can make things so much easier and can handle edge cases much more gracefully. To a certain extent, they’re even self-documenting. Here’s an example: let’s say you have an API key. Is it passed in as a header, or a param? If so, what’s it named? Or maybe you use basic auth, and leave the user blank? Or use the site username? Or pass the token as the user and leave the password blank? With an SDK, you’d just have to do “setKey(…)”, and you’re done. No remembering to pass it in each time, or figuring out where it goes. It just works. Status of service If an API stops working, it’s not always obvious if it’s the provider’s or the consumer’s fault. Let’s say you have an API that does an action and then asynchronously sends an email. If the email sending is down, the user may think they’re doing something wrong. Clearly communicating any issues can save users hours of debugging. Users turn to documentation to find out why something isn’t working, and it’s especially frustrating if it used to work and nothing has changed. Fin As developers, we spend most of our lives staring at documentation. It’s the interface between us and the code. There’s so much we can do to make learning a new language, framework, API or library easier — and very little of it involves writing more text.