Our great sponsors
-
-
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
-
-
Puts Debuggerer
Ruby library for improved puts debugging, automatically displaying bonus useful information such as source line number and source code.
-
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.
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 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.
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.
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.
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.