Documentation As Code

I’ve been working at Empathy since September 2019, and I’m really excited to be part of this company!

But some time ago, I started to see a problem.

At this moment all the documentation that the company has, is in a kind of kitchen-sink space called Confluence. Managers, developers, designers, interns… all the people in the company — even customers — can, with the right permissions, create their own pages and edit other people’s pages.

When I tried to search for some documentation about a tool, a process or the IT infrastructure, I might search for more than 15 minutes without any result or, after the research, find something that was out of date.

This is a problem particularly for people who are new to the company. The onboarding process already requires substantial time and indeed, productivity is lower during that time. Rapidly changing information from a multitude of sources adds to new employees’ obstacles.

But there is an easy solution: Documentation As Code.

Technical documentation

Some documentation is more important than others. The technical documentation is the most important part of an IT company. Typically, companies are divided into teams, and the teams are changing over time. Some people change between teams inside the organisation, new folks come to the company, or colleagues leave the company, but the IT services provided for the company, the code and the documentation still continue growing and improving.

The process for documentation should be accessible and clear for everyone in the company. If this is the case, then people can swiftly execute some processes which are trivial and repetitive, releasing time for important tasks that we need to perform.

The process

For the past few years, companies have invested in Documentation As Code. The process is simple: A developer owns a repository shared with the rest of the team, builds the application or service and keeps the code safe in the repository.

The developer also includes the documentation as part of the repository, close to the code. Some documentation might be autogenerated if the code is well formed. The possibilities for performing this process are infinite. But all of them require internal process culture, and developers must in some way be strictly obligated to follow the process.

Another important key is the markdown syntax. And you can find all the documentation about the syntax here. Markdown files are powerful and easy to manage. The result is consistent, unified and beautiful.

The advantages of this process are many: version-controlled documentation, pull requests with code and documentation review, consistent design to documentation and a million ways to perform documentation with markdown syntax.

The disadvantages are basically that the culture needs to be created across the whole company, and non-technical people must learn the basics of git and markdown.

The tool

There are thousands of tools to generate documentation from code or to create awesome websites for documentation. After some research, the team decided to give Docusaurus a try.

Docusaurus is an Open Source project based upon React. It was developed by Facebook. It takes markdown files and builds a simple application which renders the content in an appealing manner. It supports translating and versioning. It also has a search bar to find the documentation you need.

I would like to explain in a stepwise guide how easy it is to create and get value from a Docusaurus application. Let’s go trigger some commands!

Installation

Before starting, be sure you have installed Node.js. Follow its installation instructions if you don’t have it already installed. To check if it’s installed, run in a terminal window:

node -v

If you see something like v13.13.0, you are ready to install Yarn. Follow its installation instructions and verify the installation running:

yarn version

If you see something like 1.22.4 , you are ready to start!

Start an awesome site

• Execute the following command to create the project and install the dependencies using npm:

npx @docusaurus/init@next init awesome-doc-site classic

• Go to the path created for the project and run the application with the following commands:

cd awesome-doc-site

yarn run start

A new browser tab will open with the application running in http://localhost:3000. And that’s it! You are already running the application.

Application structure

The project directory will look like this:

Application Structure

• /blog/: If you plan to have blog entries in your site, it also is possible to add those entries as markdown files.
• /docs/: The documentation folder. Add the markdown files for the docs under this path.
• /src/: Non-documentation files for React components. Contains the index.js file for the index page on the site. Edit this file to customize the index site.
• /static/: All static files such images or fonts should be here.
• /docusaurus.config.js: The configuration file for the application.
• /sidebar.js: This file is mandatory to specify how the markdown files should be structured in the application.

Add the first markdown

Now it’s time to create the first documentation file. So let’s do it:

• Create a file in the/docs/ path called test.md with this content:

---
id: test
title: This is a markdown test file
sidebar_label: This is a test
---

## This is a subtitle

This is normal text!

Take in mind that the id is mandatory and needs to be referenced into sidebars.js.

• Change the content in sidebars.js to:

The id of the document is added to the sidebar.

• Open this link: localhost:3000/docs/test

Magic! The markdown is rendered and looks so good. Now you are able to add as many documents as you need on the website.

Customize the application

It’s time to create the application of your dreams:

• The index page can be customized modifying index.js file under /src/pages/.
• You can style the app by just adding styles to the custom.css file under /src/css/ . You can even convert this file into a Sass/SCSS file by installing a plugin and adding it to docusaurus.config.js.
• Add the images you need for the docs and the site under the static/img path.
• You can modify the most important configurations in the application in thedocusaurus.config.js file, such as the header, the footer, plugins or the theme.

Check Docusaurus docs

The Docusaurus website itself is built using Docusaurus. All the guides and API References are written using markdown files. You can check all the docs here.

Last step

Now that you have an application and Documentation As Code, you just need to use your favourite git cloud provider to store the application safely and be able to append a git flow for the collaborators.

I suggest to protect master branch so anyone can directly push changes to this branch. The changes should be added in a feature branch and then, a pull request will be created against master branch. Other team members could review the documentation before publishing it to the public (or private) site.

If any change is published erroneously, older versions are ready to be deployed back to a previous commit.

Conclusion

After less than one month using Docusaurus and creating the culture in the company to use Documentation As Code, the results start to appear. People can read docs easily, the documentation is up to date because after any code change the docs are also updated, and the most important thing, new people in the company can be productive from the first day.

So be productive writing your Documentation As Code and forget about wasting your time trying to find something which even probably doesn’t exist!

*Picture author: jcomp