Docs-as-Code 101: An Introduction to Static Site Generators for Technical Writers

Overview

This article is a summary and adaptation of research I presented to my Docs team colleagues in my last role as a Lead Information Developer. It was part of a years-long influence campaign to get our Confluence-only work to slowly, but confidently, migrated over to a Docs-as-Code (DAC) toolchain. I collected resources from well-known and respected experts in the tech writing field and boiled the high-level concepts down to an introductory perspective.

While we didn't realize my vision during my tenure at the company, and in the intervening years DAC tools have exploded and changed, I think this original primer is still a useful tool in the toolbox for tech writers starting their own journey with the methodology.

Concepts

Static Sites

Source: Static Site Generators: What, Why, and How

A static site is a collection of web files (HTML, CSS, etc.) delivered to every visitor exactly as it's stored.

• Pros: Fast, secure, simple, responsive.
• Cons: Repetitive to build.

Static Site Generators (SSGs)

Source: Static Site Generators: What, Why, and How

Specialized languages (Jekyll, Hugo, Sphinx, etc.) that use templates to automate efficient building and displaying of static site files as HTML.

• Pros: Fast, secure, scalable; computers handle the repetitive building; JavaScript compatible; Git-powered versioning.
• Cons: Requires varying levels of coding proficiency and hands-on configuration.

Note: JAMstack is another static architecture for building fast, modern websites. It integrates well with SSGs, but an SSG is not JAMstack and vice versa. Learn more at jamstack.wtf.

Diagram Traditional CMSes vs. SSGs

Source: Writing Tech Docs Like a Hacker with Jekyll, Tom Johnson

Docs-as-Code (DAC)

Source: DocsLikeCode.com

Docs-as-Code is a methodology to create documentation as close to the source code of your products as possible. It involves adopting the tools and processes of developers, like Git and CI/CD, to encourage deep collaboration and contributions from across the organization.

• Workflows involve: Writing, reviewing, testing, merging, building, and deploying docs constantly, similar to how developers handle code.
• Storage: Documentation is stored within the same repositories where product code is stored. SSGs compile these artifacts and publish them as an HTML website.
• Collaboration: Successful DAC executions require deep collaboration with development teams. This is a great thing, but it must be a working arrangement negotiated and prepared for far in advance!

Authoring Documentation for SSGs

Source: MarkdownGuide.org

Most documentation for SSGs is written in Markdown, a lightweight markup language that allows you to format elements in plain-text documents. Authors create and publish documentation via IDE/text editors like VSCode. Of course, markup languages vary per the dozens of widely released SSGs. Markdown just is the most-common.

Note: AsciiDoc (XML-based) and reStructuredText (Python-supported) are additional markup languages used by some SSGs. While Markdown is more ubiquitous, it isn't preferred by all documentation teams.

Hosting and Deployment for DAC Workflows

SSGs don't handle hosting and deployment on their own. You might create an entire static website offline on your own computer, run it locally, but never publish it to the web. Hosting options include:

• Netlify: Automatically picks up changes from your GitHub repo and rebuilds your doc website whenever you push/merge updates.
• CloudCannon: Designed for Jekyll deployments with a suite of add-ons, including authentication and SSL.
• AWS S3: A flexible option for hosting static sites, where you can automate rebuilds whenever you push changes to GitHub.

Regardless of choice, you'll also want your team to investigate additional hosting features like content delivery networks (CDNs) and SSL security, which are crucial for maintaining uptime performance and security within your portal.

Top SSGs for Documentation

• Jekyll: Ruby-based, mature dev community, and the most popular SSG for documentation. Robust Git-based CMS backend integrations available.
• Hugo: Golang-based, maturing dev community, Git-based CMS available.
• Sphinx: Python-based, built specifically for documentation, requires authoring in reStructuredText.

Q: Why Not Stick with Confluence?

Source: Modern Technical Writing: An Introduction to Software Documentation, Andrew Etter

Wikis have huge benefits and huge drawbacks. Users don't need to install any applications, clone any repositories, or learn any strange workflows. They can spot an issue, click Edit, and fix it within ten seconds. Also, every major wiki has out-of-the-box search, a huge improvement over most static site generators. One major problem, however, is that wikis are web applications. If you decide to create and host one, they require maintenance over time. And if you've ever worked at a company with an internal wiki, you know how often they crash or slow down. Yes, Wikipedia has proven that wikis can scale to a huge number of users with good reliability, but that scaling is the result of a ton of hard work from some very smart people…whose job it is to manage the site. Static sites are indisputably simpler to manage. To be blunt, writing on a wiki sucks. Everything in a web browser is so ephemeral, ready to be flushed at any time. Ever gotten work done from a plane, train, park, or hipster coffee shop that refuses to offer wireless internet access? Not with a wiki, you haven't. With static site generators, you have everything you need to write, build, and review changes locally. When you have connectivity again, you can push your changes and update the website. For a wiki to make sense, your documentation should never need to be versioned. You also shouldn't mind writing in an inferior editor, only working online, and maintaining a piece of enterprise software.