This article was written by David Cheung.

Levelling up our docs

We’ve been heads down working on Zero for the past while, but as the scope expands and features get more complex, we are at the point where markdown files in GitHub need to be organized better for ease of readability and discovery. So we’ve built a documentation website! 

Requirements for the documentation site

Code should live with its docs

Documentation is part of the software—if users can’t figure out how to use the software, then there is no value delivered. If the docs aren’t in the same repo as the code, people will invariably forget to update them, and if the docs are out of sync with the code, they are almost useless.

For an open source project, if a community member is generous enough to share their improvement back to our project, we want to make documenting their work as hassle-free as possible. If contributors had to clone an entirely different project just to document their work, it becomes twice as hard. 

Low maintenance

We don’t want documentation to be the reason someone didn’t contribute to our project, so it has to be easy. All our existing documentation is already written in markdown—we think it’s the best format because even pre-rendered it’s designed to be highly legible, making it easy to consume and easy to edit. 

Nice to haves

In this cut-throat world where everything is ROI, we also want to pick the tool that offers the most benefit for our effort, so we have to be as greedy as possible. What we’re looking for in a tool: 

• Highly customizable and extensible, so we can control the look and feel

• A large user base for ease of learning and support

• A proven success, with large, complex projects using it

• A modern stack, so it doesn’t become obsolete quickly

• Feature rich, so we don’t have to build many common things everyone needs

• Easy to deploy, so it can easily live with our code

Docusarus 

You may think the cute green dinosaur drew us to Docusaurus, but let’s not be so shallow. Let’s see how this green dinosaur checks all the boxes, and in many cases surpasses our expectations for how easy it is to add certain features (see feature rich below).

Docs living with the codebase:  

The doc site can be completely isolated in a folder in the root of the project. 

Low maintenance:  

With the Docusaurus 2.0 beta, generating the navigation is easier than ever, you can simply specify the folder where the documents are. The setup also allows fine-grained control of the sidebar order and display with a couple lines of metadata and it will do the rest.