From Readme to Docusaurus: How an intern saved us $1.2k
Humans tend to overcomplicate, and devs are no exception (on the contrary!). We were paying 99$ a month for a Readme subscription and feeling a lot of friction. Along comes an intern looking for project ideas, and we couldn't be happier.
The road to Readme
Like many other startups, Reviewpad started its documentation on Notion. We use and abuse Notion internally (❤️). It was logical to create a new workspace for the documentation and give it a custom domain with super.so. It was a no-brainer: cheap, quick, easy, and pretty.
Notion+Super.so lasted quite a while, until we started to iterate faster and had the need to serve documentation to several versions of Reviewpad. That's when you go for the big guns: Readme, Gitbook, and Docusaurus.
We discarded Docusaurus pretty fast because it had to be self-hosted, and it didn't have a GUI to compose new versions. Little did we know these were its main advantages.
We eventually decided to go with Readme. At 99$ a month, it's a hefty price for any startup. Readme was very kind to give us a 50% discount for 3 months which, together with the urge for a new documentation platform, somehow convinced us to go for it.
Readme was pretty nice: easy to set up, responsive support, nice UI, fast, and all the features that we needed were there. We were happy for a good while.
The breaking point
Only after making serious usage of Readme, we found out the friction points. To highlight the main ones:
- No automatic import of documentation generated by us
- A (new) UI that was slow and broke down all the time with bigger than usual pages
- Poor link preview on social platforms
- A heavy $1.2k yearly burden
With time, it became harder and harder to make a business case for Readme: it was very expensive, it was the source of a lot of frustration, and we kept seeing a lot of dev tools using free and open source documentation tools that looked very good.
We put up with these pains for a while until our intern, Pedro, had a spare month at the end of his internship. We sent him on a quest to replace Readme.
The quest to replace Readme
Phase 1. Finding a substitute
The quest took one week, and Pedro will admit that he only needed a couple of days. That's because he went deep and was trying out as many documentation platforms as he could. When he saw the time running out he decided to have a deep look only at the two most used ones: Material for MKdocs and Docusaurus.
Phase 2. Testing
For two weeks Pedro set up and fine-tuned an instance of Docusaurus, as well as an instance of Material for MkDocs. That gave us plenty of time to try out the platforms and make sure there weren't any missing features or hidden red flags.
This period was essential to compare the two platforms and make our decision. Here's a quick comparison of the pros and cons:
| Docusaurus | Material for MkDocs | |
|---|---|---|
| Pros | Sleek UI Uses React for the UI (easy to extend capabilities) No paid features | Sleekier UI |
| Cons | No search out of the box | Some features were paid |
We decided to go for Docusaurus, mainly because it's built with React which we are pretty comfortable with, making it easy to bend it in whichever way we need in the future. Also, maybe due to React, it was a bit snappier than MkDocs.
It's important to say that both platforms offered on-point documentation (surprise!), the installation and configuration process was stupidly simple using each platform's documentation with absolutely no need to find guides or tutorials anywhere else. 💪
Phase 3. Importing, deploying, sharing
The last week was spent importing all the docs from Readme into Docusaurus, setting up the architecture to preview and deploy Docusaurus in GitHub (FREE!) infrastructure, and finally educating and documenting the whole process with the Reviewpad team.
And that's how you save a company $1.2k a year in the last month of your internship.
About Docusaurus
Docussaurs is:
An optimized site generator in React. Docusaurus helps you to move fast and write content. Build documentation websites, blogs, marketing pages, and more.
docusaurus.io
Challenges
Architecture and deployment
This was the first challenge, and though it was not necessarily related to Docusaurus, it was one that we needed to sort out. It's not complicated either, with a few YAML lines of configuration you can make Docussaurs build and deploy automatically to GitHub pages.
Collaborating with other people
You have Docusaurus up and running on your machine and you're able to deploy the build to GitHub pages, but what if you want to show something to a colleague? Out of the box, the solution was to push the changes to GitHub and have a colleague check out the code to run Docusaurus on their side.
For this we use AWS Amplify Previews, which is triggered by any PR against the main branch, that automatically spins up a machine with the new version and posts a link in the PR. Super handy.
Search
There's no search out of the box because Docusaurus is a static website, however it has support for several search engines, the main ones being Algolia and Typesense:
- Algolia: best in class, paid but free for open-source
- Typesense: second best in class, free and open-source
Fun fact, Algolia used to be open-source, Typesense is a fork of Algolia before it went private.
