Build vs Buy: API Docs

In October, I joined Mailinator as a part-time Developer Advocate. I immediately spotted a problem that all my future work would rely on: fixing the docs! The old docs weren’t just ugly; they were frozen. On the surface, everything looked fine. There were no burning support tickets or "official" complaints. But under the hood, we were living in a state of documentation debt. Dependencies were old and out of date. Deploying was a minefield.

I wanted a fresh start.

Out of the Box Solutions

My initial instinct was to go with GitBook. I’d used it before and loved the polished UI. I spent the first phase of the project syncing GitHub repos, designing the layout, updating content and, most importantly, modernizing our API docs.

I moved everything over to an OpenAPI (Swagger) specification. There is a certain peace of mind that comes with having your endpoints, schemas, and parameters strictly defined in a spec file. You make changes in one place and that’s the specification. Then the documentation system interprets and generates the individual API endpoint pages for you. It's pretty neat.

Then I hit the paywall. I knew GitBook cost money. What I didn’t realize was that in order to get the url structure we wanted http://mailinator.com/nameofdocs, it would require a plan costing over $250/month. That’s a massive “convenience fee”, and more than triple what I was expecting to pay.

No thank you.

The messy middle

I noticed many of the documentation sites I enjoyed using (WebDriverIO, Cypress, Playwright, Selenium) all had one thing in common: Docusaurus. It is free, open-source and generates static files. That meant I could simply drop the files into our existing doc server.

However, free isn’t always free:

• Getting Docusaurus running locally is easy.
• Building content for it is easy.
• Getting it to do what you want is much harder.

Unlike GitBook, Docusaurus doesn’t come with a native, API reference generator out of the box. (I didn't want to create those pages myself.) I found myself in the hunt for community plugins. I evaluated several, eventually landing on docusaurus-openapi-docs.

I was jumping through hoops, creating an NPM account for the first time just to handle the packages, and wrestling with configuration scripts. I had to write a custom script just to get the sidebar to render the way I wanted.

Despite the friction, I pushed through.

Ownership

Once the dust settled, I realized I had built something far superior to a "rented" solution. I understand why companies would pay $250+/month for an easier, out of the box solution. You’ll save a lot of time.

But now, with Docusaurus, I can run the entire site locally and see my updates in real-time. (A feature GitBook’s web-based editor simply couldn't match.) By adding an "Edit this page" button to our docs, we’ve invited our users to help us improve the docs.

Best of all, we have total ownership. I’m (mostly) done configuring, and I can get back to what I actually joined Mailinator to do: building great content!