Docs as code: how we built documentation that keeps up with shipping

We needed a system of documentation for our organization. The goal was to have things well organized so we could easily reference previous decisions and changes. I began researching how big and renowned companies go about keeping their documentation current while still rapidly shipping software. What I found is that the best standard approach to documentation today is treating "docs as code."

During my research, I came across the acronyms ADR and RFC. In a simple system, it basically goes like this: before coding, you write an RFC, which stands for Request for Comments. This is where the team can brainstorm and debate how to solve a specific problem. Once everyone reaches a consensus, that final choice is locked in and recorded as an ADR, or Architectural Decision Record. From there, during the implementation phase, you edit the affected documentation, whether that's the Readme, an API contract, or a guide, in the same branch and preferably in the same pull request as the code itself.

To structure the actual content, I came about the Diátaxis principle. It's a systematic approach to technical documentation that argues there are four types of documentation, and each type has a different purpose and needs to be written in different ways. The first two focus on what the user does (action): tutorials for learning, and how-to guides for achieving specific goals. The other two focus on what the user knows (cognition): reference materials for information, and explanations for deeper understanding.

I also felt there should be a library out there that helps us build this out. I remembered we already knew about Mintlify because I once did a workshop on it, presenting it to the team at Isaac the Creator. In my latest research, I came across Mintlify again, as well as Gitbook, but the main guy we went for was Docusaurus. We went for it because it's open source and free. Docusaurus is packed with features like built in search, versioning, and localization. It relies heavily on Markdown and MDX, which allows devs to easily write and maintain docs while also letting you drop React components straight into your markdown. Since it runs on React, you can even create custom plugins for the documentation site.

After watching some YouTube videos on how it works, we implemented it across all our repositories in combination with the Diátaxis principle. We then had to figure out a way to separate our client facing docs from our internal docs. We came to the conclusion of having separate folders and builds for each. The domains and hosting setup was handled by Ife on the backend team, and everything just clicked.