Because Web APIs are still fairly new, the quality and format of their documentation varies a great deal. Good documentation is important in encouraging and keeping developers interested in your platform as well as reducing support costs.
We have to be experts at finding ways to do more with less. And while that skill set is highly valued in development, it doesn't always transfer over to writing great documentation.
API documentation has to be more than bare necessities like methods and endpoints. It needs examples, summaries and fleshed out explanations.
Unlike coding, you're writing for an audience of humans, not computers. Humans come from all backgrounds, with different experiences and perspectives that all need to be addressed.
But even if you're committed to writing great API documentation, it's hard to know where to start.
There's no API documentation guru whose mentorship you can seek, nor a standard how-to guide for documenting your API. So we figured it's about time to make public some of the best practices we've developed over the years for writing and updating lucid, navigable, and error-free API docs.
How to start writing API docs Developers often have a certain user persona in mind when they write documentation. They make assumptions about API consumers' knowledge base and how much they're willing to put up with to get a good understanding of how the API works.
But your API consumers aren't so different from a standard software user, even if they are developers. If the UX of your documentation page sucks, they'll give up and forget about your API like a bad dream.
Here's how to improve the user experience for your documentation. Create minimum viable documentation Writing API documentation from scratch isn't exactly a weekend project.
The best API docs take years to build, iterate, and perfect.
But that doesn't mean you should spend months on your documentation before giving your consumers access to it. Developers love Twilio's API docs. They're robust, thorough, and come with plenty of resources and tutorials that let you dive right in.
They didn't build it overnight, but they did have all the proper pieces in place: As they built out their product, found more use cases, and addressed queries, they updated the site, equipped with a nicer, sleeker UI. Browsing through this redesigned website, you'll find more quickstarts, more REST resources, and more error handling.
Establishing the framework of the site from the get-go enabled Twilio to update as they grew and improved their product. And once they became known for their thorough and remarkably clear documentation, they had a reputation to uphold. They recently updated the design again, with an even nicer UI.
A framework and all the vital information for a user to get started is enough to publish. From there, work outwards, adding resources, edge-cases and examples. Most importantly, keep the user experience front-of-mind.
Begin with a dynamic layout Post, a static layout hints at an outdated product. It's also difficult to navigate through, since it's essentially just a several-hundred page manual thrown onto a website. But if you create a dynamic layout from the get-go, it will be easier for your users to navigate, and for you to expand as you scale your documentation.
Here are the essentials for a modern layout.
Stripe famously pioneered the three-column layout, with examples of code on the right and a navigation column on the left.
Multiple columns let you see examples in context so that it's easier to understand how the endpoints work in the real world. This is a small detail that every developer appreciates. Improve the readability of your sample code so that it's easier to scan and process the different components.
Everyone hates the disappearing nav bar—the one that you have to scroll for five minutes up the page to get back to. Keep your nav bar in sight at all times so that it's easy to hop through different parts of your documentation site.
Many developers use tabs as a way to organize examples in different languages. This way you have only the most relevant information in front of you.What is the best tool for generating RESTful PHP API documentation? Update Cancel. Answer Wiki. 10 Answers.
Alex Walling, He or she would be happier to write codes than docs, really. k Views · View Upvoters. What is the best tool for generating API documentation dynamically? For training new developers and keeping your documentation living all in the same place, Process Street is a solid choice for software documentation.
We use our own product for as much as possible, and since it’s a way to create and share structured documents, it lends itself perfectly to this purpose. What is the best documentation tool you can use for both web and desktop software documentation?
Swagger API or OpenAPI support; Private documentation with identity providers GitHub, GitLab, Auth0, and more; Which is the best way to write software documentation?
During the talk I mentioned a few API documentation tools that I’d used and, based on feedback and questions from attendees, I realised that this topic merited a blog post.
So, the purpose of this is to introduce 5 tools which help with designing, testing and documenting APIs. RAML is backed by a large open source community providing hundreds of pre-built, customizable tools for all your RESTful API needs See all Projects RAML is the only spec designed to encompass the full API lifecycle in a human readable format with code and design pattern reuse.
It’s been many years since I've documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.
Klariti Technical Writing. Technical Writing tips and tools How to Write API Documentation – Free eBook 22 API Document Generation Tools ; How to Write Your First Technical Documentation .