As a member of Algolia’s documentation team, I am often asked: “What tool are you using to build your documentation?” Of course, I answer the question, but I am often tempted to say that it’s probably the least valuable piece of information I can provide.

In this post, I am going to give you some of that information: what things you should care about when building your docs, and how those things will make the choice of tool the least important thing.

Documentation is usually composed of two big parts: the content and the software rendering it. You might have guessed where I am going with this: a quality README.md stored on GitHub can be far more efficient than over-engineered documentation that is well displayed but has issues with content.

The perfect tool is not out there

There are plenty of ways to build API documentation: static website generators (Jekyll, Hugo, Middleman), web frameworks (Ruby on Rails, Laravel, Django), dedicated doc tools (Docusaurus, Read the Docs, Sphinx), SaaS products (HelpDocs, Corilla), and that’s just the tip of the iceberg — there are so many more.

Depending on the one you choose you’ll have more or less flexibility, and more or less work to build and maintain. All tools will let you decide to a certain extent what you can do, and constrain you on the other end. I don’t believe there is a tool that can fit 100% of the needs in the long term. Documentation is something that needs to evolve, and you may have to change your tools several times as you outgrow certain constraints and have new needs.

Two years ago, we moved away from an internal tool that was aggregating content from GitHub ReadMes, a database and an external software managing our FAQ. This change took us full two months, and this is not counting the months of preparation prior to making the change.

By far the most time consuming task was to undo the formatting that our original tools required us to make. We had no consistency — some were Markdown, some were Markdown with custom extra features, some were plain HTML — and so while moving away from our previous tools, we had to edit thousands of files manually in order to unify everything.

Put the focus on making the tool fit your content (not the other way around)

Instead of focusing on which tool to use, a better option is to focus on whether you are doing everything possible to be as little software-dependent as possible. If you can respond to: “Can I switch easily to a new tool?” with a “Yes!”, then you are on the right track.

Build all components to be software-independent

While developing custom components, it’s good to keep in mind that they should be as little dependent on the software as possible.

Now, to answer that question from the beginning of the article…It’s been two years since we’ve been using Middleman for our main documentation. It’s doing the job, but it has some downsides and we’ve had to customize it quite a bit to our needs.

Here are some of the things that we added/modified:

• Custom sitemap
• Custom data files system
• Custom snippet generation
• Injections of custom metrics from Google Analytics for ordering purposes (for example the FAQ entries listed in https://www.algolia.com/doc/faq/ are the most viewed ones)
• Ability to have a snippet file that can be auto-injected into any content file
• An Algolia indexer

These customizations are done in a way that we can reuse them in any project. The modifications represent ~800 lines of custom code, which is rather small for documentation like ours, but it enables us to be able to move data files to any other software in a matter of days rather than months; this is us adapting the tool to our content.

Keep the content properly structured

What is even more important is how you organize your content so that you can re-organize it programmatically when needed, or transform it so it fits another tool.

The more structured the information is, the easier it is to:

– reuse it across different parts of the documentation
– change the organization system itself when needed

Two tips on that front:

1. 1. Keep the content centralized

As mentioned earlier, our documentation comes from a system that was split in many different parts. Today, we have documentation in a single repo that you can run independently from the main website. This removes dependencies and allows us to focus on content and doc-specific modifications. It also give us the ability to iterate more quickly both on content and code parts.

1. 2. Choose the right file format

Also very important is where you write your content. When using a static website generator, it is “the norm” to put all content inside the Markdown files. This can work for small docs, but when your documentation starts growing above hundreds of pages, with different types of content (guides, tutorials, reference, FAQ), and you are seeking consistency, using structured data files is a better approach.

That’s why at Algolia we documented all methods and parameters in yml files and not Markdown files. While we ended up with Markdown inside yml, which can seem a bit counter-intuitive, it is quite useful. It also allows you to reuse the content in different ways across the website.

The two pages above are generated from the same yml file. When editing, this makes it very easy to keep consistency between different parts of the website.

So by focusing in this way on content first – its needs, structure, maintainability – and then finding and customizing the tool, you can come up with a documentation that is easy and quick to evolve.

Once this is in place, a good next step is to have your team and customers contributing content. Which leads me to …

Bonus tip: get more contributions from the team and your customers

….and make those contributions as frictionless as possible.

There are a few actions we took to achieve this. When logged in as an admin, next to every section or code snippet we have an edit button that links to the correct file in GitHub, enabling admins to modify the content he or she is currently viewing.

Let’s take an example of a new developer joining the team. One of the first things they are going to do is learn about the product by working with it. The easiest route for that is using the documentation. While they are using it, they will notice typos, unclear bits, undocumented features…if they have to think about where to provide feedback, or how to edit the file, there is a high chance that they will do nothing and switch to another task.

And if that’s true for your team, it’s even more true for customers. It is very unlikely that a user who noticed a typo will look around the website for the support email to tell you that they found something wrong.

This is one of the reasons we have the following big form at the bottom of every documentation page and also accessible from every section of the content:

The customer cannot miss it and that’s the point: if they see it once they know it’s there and the friction to contribute is low.

This also has the benefit of giving a great developer experience to our customers. When someone reports an issue on the doc, it goes straight to our regular support channel, where we have a good response time. We also fix and deploy a majority of the issues within the same day. A company that takes immediate actions on feedback gives an impression of care (one of our core values), and that’s exactly what we are aiming for.

When someone in the team creates or updates a PR, the change will be rebuilt and deployed to a new domain. To achieve that, we use the continuous deployment feature of Netlify, which brings several benefits. The main one is ability to preview, not only for the person doing the PR, but also for the person reviewing it, because they don’t have to deal with running the doc locally for small changes.

This is just one example of how to reach out to your readers. It creates a virtuous cycle where everyone (team + customers) contributes more and more, and enjoys doing it.

In short…

There are so many things to consider before worrying about which tool to use. Naturally, you do have to start somewhere and choose a tool, so I advise you to choose the one you and your team are most comfortable with. Just keep in mind to focus on the content, and adapt the tool to the content, not vice versa.

We’d love to hear your feedback and other experiences with this topic: @maxiloc, @algolia.