How We Built Our Documentation on Docusaurus

1

Vercel

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.

#Developer Tools #Web Development Tools #App Deployment 522 social mentions

2

Git

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.

#Git #Git Tools #Code Collaboration 214 social mentions

3

GitHub

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.

#Code Collaboration #Git #Version Control 2037 social mentions

4

Docusaurus

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.

#Documentation #Documentation As A Service & Tools #Static Site Generators 192 social mentions