Select a Static Site Generator

If you want to start new product documentation for a startup, you have literally hundreds of options. When I did this before, I thought “Wow! I have a clean sheet of paper!” In other words, with a few limits, I could choose the tool that I wanted.

When software technical writers create documentation, they need tools. Sure, I could have used Microsoft Word, but I’m a believer in “docs-like-code,” as described by Anne Gentle’s book of the same name. When I asked ChatGPT about this, I liked this part of its response:

“It’s a cultural shift towards valuing documentation as an integral part of the development process.”

Then I started investigating. I had a few parameters which limited my choice. As a “lone writer,” I needed help on two levels:

• I wanted to encourage others to contribute
• I needed help from others to help me build the docs-as-code tooling

If I had the budget, I could have selected one of the proprietary tools. In theory, it would have made my life easier to pay for dedicated support.

While XML tools (DITA, Docbook) are popular options, most developers that I know hate XML. I didn’t want to “bend over backwards” just to get them to read draft docs.

As an open source enthusiast, I wanted another option. From past experience, I know some communities provide support that rival that of expensive proprietary tools. And open source tools are easier on the budget.

So I wanted an open source solution. Fortunately, there are many open source options. Per Jamstack, there are over 300 Static Site Generators.

Based on experience, my knowledge of the communities, and the capabilities of the tools, I limited myself to the following choices:

• Jekyll. Written in Ruby, Jekyll supports liquid tempates. I used Jekyll in a past job.
• Hugo. Written in Go, Hugo is the SSG for Kubernetes, Digital Ocean, and Linode. Some developers that I worked with favored Hugo.
• Gatsby. Written in ReactJS, Gatsby is known as the option for larger documentation sets. The front-end that I worked with is built in React. However, learning Gatsby would have required a serious time investment.
• Docusaurus. Also written in React, Docusaurus is sponsored by Meta. While it’s also written in React, it would have taken me less time to learn than Gatsby. Unfortunately, it did not (at the time) support integration with the company UI.

I chose Hugo because of:

• The quality of availble open source examples. If you look at the source for Kubernetes documentation, you’ll find doc tooling that “does it all.”
• The quality of the community. I needed a “theme,” and the community around Docsy provided everything I needed, including a “template” from which I could “cut, paste, and write.”