How We Built Our Software Documentation On Docusaurus

It requires an ample amount of time, effort, and resources to produce great, user-friendly documentation. Good documentation is fundamental to the way engineers get started with a product and ultimately use it in the long run, which makes it essential to both user retention and growth. Building our documentation at Courier was a task we therefore took very seriously.

We originally created our documentation for a very small, specific audience with specific uses for Courier. Over time, however, our user base, their use cases, and our product itself has grown dramatically. To cover our bases, we needed to improve and expand our documentation and this time, we wanted to make it scalable and with a focus on a great user experience. We decided to use Docusaurus to do so, which allowed our engineers to collaborate and update our documentation more efficiently. Here’s how we built our documentation and what we learned in the process that might be useful to you.

Identifying challenges with our documentation process

When we first started Courier, we just wanted documentation that explained how to use Courier as a product. So, we found a tool that could help with that: ReadMe.

ReadMe gave us enough features to get started with our documentation. We could create and update our documentation when needed and without much effort, but we couldn’t collaborate as much as we needed and could only save one draft at a time. This was a major challenge because anyone could easily overwrite another’s work if they were working on the same file at the same time. ReadMe also had a flat file structure which was inconvenient to use. There was also no real Git integration into their CLI, so we had issues with document versioning and collaboration. Ultimately, this meant that docs were in the approval process for an unnecessary length of time and not everyone was able to make suggestions for improvement as they came up.

So some years and a few significant product updates down the line, we knew that it was time for a major documentation update. ReadMe was easy to get started with and served us well for our first couple of years, but we needed something that addressed our more specific pain points.

Prerequisites for a documentation tool

So we knew we needed something new. The next step was to decide which solutions were necessary to address our pain points for the next version of our documentation. The team came up with a list of requirements for documentation tools we would use in the future.

Limitless Collaboration

A happy challenge with a growing company is the need to scale almost every aspect of it as the team and product grow. As Courier’s technical team grows, we have more subject matter experts to provide input on documentation, which is good news for the quality of docs. However, more SMEs mean that we need more people to be able to collaborate on a draft at a time. Since the team will only continue to grow from here, limitless collaboration was one of the basic necessities for our future docs tool(s).

Versioning

A growing company comes with the inevitability of a growing product. As new versions of the product are released, there will always be an overlap time when some of our users are using an older version of the product and some are on the newest version. Our documentation needs to cater to both of these groups of users, which means to make sure everyone has the correct information, versioning is an important docs feature. For example, we need to keep the documentation of our API 1.0.0 version separate from the one for API 2.0.0 and ensure that it is possible to update and switch between versions quickly and easily.

Version was also important to allow for the option to separate and store drafts away from the official documentation so that the team would be comfortable working without the pressure of a breaking change.

Link Validation

One of the worst things that can happen to user experience in product documentation is for a user to click on a link and get a 404 error. It makes it more difficult to keep users in the docs and following instructions, which can ultimately affect how many users successfully get started with the product and/or are able to troubleshoot on their own. A docs tool that would include link validation for internal links would go a long way toward avoiding damaging errors and UX issues.

Localization

We have customers from different ethnic groups all around the world who speak a diverse set of languages. To cater to a global audience, users need to be able to read our documentation and get the help they need, regardless of the language they speak. Localizing our documentation like link validation, improves user retention and UX.

Docusaurus matched our list

With our list in place, we were able to begin researching to find the right new tool. After some research, we discovered that Docusaurus, which is built on React, allowed for limitless collaboration, versioning, link validation, and localization.

With Docusaurus, we built our docs as markdowns and exported them as a static site. We created reusable custom components and now have complete control over how we build our documentation. The MDX integration is also particularly useful, as it allows any JavaScript code to be embedded into the .md file.

With a few lines of code, we could tweak our theme to suit our brand colors or customize any part of our documentation by swizzling the components we wanted. We also could use plugins to extend the functionality we got from Docusaurus. An example is the plugin for our search feature that allows customers to find relevant documentation.

I also built our custom API explorer myself, which enables developers to try out our API methods directly from our docs. I built it as an embedded React component placed in the MDX file. Because we host our documentation on Vercel, we could utilize Vercel Functions to proxy the API Explorer requests to the Courier API through our docs backend endpoint.

With Docusaurus, we have been able to build our documentation quickly and easily. We can now make updates by simply cloning the repo on GitHub, branching off our main branch, implementing the changes, and creating a pull request (PR). Once someone has reviewed and approved the PR, it’s merged with the main branch, which deploys to Vercel and updates our site with the changes.

All we need to contribute to our documentation is a GitHub account and an integrated development environment (IDE). This helps us keep track of every maintenance task for our documentation.

What’s next for our documentation?

There are a few more goals we have for our documentation. We have yet to utilize Docusaurus’s localization feature, so that’s in the works. We have also recently made our documentation open-source to welcome external contributors. This way, the user can take ownership of the updates they want and help themselves and others who would benefit from their contribution.

Until then, learn to use Courier via our documentation and tutorials. We also live stream content that’ll help you get started and continue with Courier.

Also Published here