Have you faced API projects, where the links are not working? Files can not be downloaded? There are loads of data, but you don’t know how to access it or use it? Or you will just be redirected to Github page with short project description? Are you developing an API and get an error state which hasn’t been documented?
Writing an API documentation, or any documentation in that matter, is something that most of the developers hate. It takes lot of time and patience, it isn’t that exciting or media-sexy job. This is understandable, nobody likes the “boring” after work and shortcuts are so much easier. Still, properly designed documentation, which is made with care and love, is the core of the whole project. How else would you get people excited about your project? How else would you get the end-users to know how to use the data?
Learning a new API can be hard. In the beginning learning curve is steep, you are exposed to complicated new ideas. There are examples with abstractions, and with unfamiliar languages. There are way too many clicks (which we all hate), because the documentation is spread onto several pages. You really don’t get the big picture of the project and oh boy, the documentation text is so boring.
James Fu from Parse has, in one of his blog posts several years ago, given some basic tips for documentation. Those are so true and valid, that we list them shortly here:
· Documentation should include reference, guides and tutorials. Adding your personality to text will help keeping the readers awake.
· Sprinkle real world examples throughout your documentation. Nobody will think there is too many of them.
· Minimize clicking, keep the related topics on the same page, don’t spread them here and there.
· Include a gentle Quickstart, walk through for the minimal steps needed to do the smallest thing possible in your API.
· Use multiple languages and let the developers choose between them in the examples (Ruby, Python, Java…)
· References should include every edge case and every assumption that is made, it can save hours of your user’s time.
· Best way to show the full picture is to give sample applications. Application code communicates also how you API integrates with other systems.
They say that way to man’s heart is through his stomach. We believe that the way to a developer’s heart is through great documentation. Sounds boring, but it will pay off.
Posted by Laura Ekman, Apinf-team
