Static Site Generators for Documentation

November 13, 2018

We are using some internal libraries at work that are not very well documented. As a result it is really difficult and time-intensive to onboard onto the project. It became clear to me that not having good documentation can come at a very high cost when it comes to long-term productivity for a team with changing team members.

As a result I started to work on documenting the inner workings of our application and it does feel satisfying to bring it to paper.

With documentation on my mind I attended our local JavaScript meetup KarlsruheJS, which I also co-organize. Interestingly it featured a talk about VuePress a static site generator based on VueJS which is specifically tailored towards creating documentation. I was smitten instantly!

After tweeting about my excitement about VuePress KarlsruheJS member Carsten directed my attention towards Docusaurus by Facebook, which is (obviously) a React-based static site generator for documentation. And since my co-worker Emma is totally into Gatsby I took a closer look there too and also found a Gatsby theme for documentation as well.

My docs are not ready to be hosted yet but it is good to know that there are some solid ways to get a documentation site up quickly. Since our project is written in React I will not go with a Vue-based solution though. It will be either Docusaurus or Gatsby.