Why Your API Documentation Shouldn't Rely on a Tool

Algolia’s Maxime is often asked what tool the company uses for API Documentation. He gives the name but he’s tempted to say it’s not an important question. What matters more than the software rendering your docs is the quality of the content. A good readme.md in GitHut is going to be more useful than nicely rendered docs that make no sense. Over at the search company’s blog, Maxime explains what is important and how to create your docs in a way that won’t give you headaches later on. 

There’s no shortage of tools to build documentations. You can use static website generators like Jekyll, web frameworks like Rails or Django or dedicated tools like Sphinx. None of them is going to fit your use case 100% and all will impose their own limitations. As a result, you might need to change tools several times as your docs evolve. 

This is exactly what Algolia experienced. It initially built its own internal tool but moved to a third-party tool, Middleman, later on. The move took considerable time since there was no consistency in the original docs. Some were in Markdown, others in HTML. Thousands of files had to be edited manually to get some consistency. 

The lesson learned as a result of this move was: make the tool fit the content, not the reverse. You want to focus on creating content that is as software-independent as possible. That way, if you need to switch tools, the move will be painless. 

That means also making any custom components you build for your doc tool independent. Algolia had to build lots of custom components when it moved to Middleman for its docs; among other things: the sitemap, the snippet generation and the data files system. 

To help you keep things software-independent, Maxime recommends keeping content structured. Organize your content so that you can reorganize as you need when you move tool. This will help you reuse content across docs and change the organization system as needed. To help you with this, keep content centralized and choose the right file format.  So, for example, while Markdown is fine when using a static website generator, if your docs start to balloon to hundreds of pages, you might want a more structured format. 

As a bonus tip, Maxime recommends making sure your team and customers can contribute as easily as possible. Algolia did this by adding an edit button to every code snippet and paragraph so an admin could modify the content while viewing the page. This way, a developer who notices typos, errors and undocumented features while reading the docs can edit as he goes. 

Maxime concludes by stressing that choosing the right tool is not the most important consideration. Much more important is focussing on content and letting the content dictate what tool and format to use. 

Be sure to read the next API Design article: 5 Great PHP Frameworks for Building an API

Original Article

Good API Documentation Is Not About Choosing the Right Tool