Building an API can be a fun thing. You conceptualize, design, develop and of course, test and deploy your product. But what about the ‘not so fun’ stuff, the documentation? Your API would be of no use to your target audience if they do not know what, how and why. The ‘what’ tells them what your API is about, the ‘how’ tells them how to use it, and the ‘why’ tells them why they need to follow the guidelines. So what are the five things that should be at the top of your list when you want to develop simple but effective API documentation?
1. Getting started. Everybody needs to start from somewhere, sometime. A ‘Getting Started’ section is good for warming up readers to the topics you are covering. Apart from providing a concise product overview, you can tell your readers what to expect and maybe how to effectively use your documentation or user guide.
2. Include sample codes or helpful illustrations. You lead by example when you show them what to do with simple, easy to understand examples. Have someone else in your team proofread or study the examples and illustrations you have in your documentation. If your team member or reader has a bemused look afterward, then you know you need to review your work.
3. What if scenarios. What happens when the ride becomes bumpy? You can be sure things would not go according to plan, all the time. Great documentation tells the users what to expect and what to do if expectations are not met. Be sure to tell your readers what to look out for if (and when) things go wrong, the likely cause and how to remedy the situation.
4. Avoid jargon. Your documentation should be written in a structured, easy to understand language because it might be picked up by readers outside your primary audience. If your readers suffer undue stress due to your vocabulary or choice of words, it might be assumed that your product is not ‘user–friendly’.
5. Keep it updated. Have you made any change to your API? Don’t hesitate to roll out complementary documentation updates. You will be surprised at the number of obsolete API documentation out there. If you have deprecated features, be sure to remove them and keep your readers in the loop.
Documenting APIs can be a demanding task. But your API is as good as how users can quickly understand and implement it. Don’t forget, your documentation is a surefire tool to help users lessen the learning curve. Are you interested in knowing more about the API lifecycle and API documentation? Stay with me on Medium as I share helpful tips and information on APIs and API related topics.