Technical documentation is often viewed as just a writing thing, and too often an afterthought. I’m here to show you documentation is just as much of a software project as the software it documents. All the same elements are at play: source “code”, compilation, validation, testing, publishing, versioning, and yes, even (meta) documentation. And the documentation really is part of shipping the software; you could even argue the face of it.

In this talk, I’ll present various challenges that a documentation team faces and get you thinking about how to apply engineering practices to help solve them. As an engineering team, your goal should be to help writers write, not be stuck worrying about laborious tasks that would frankly horrify you if you knew they were being done manually. It’s also a good opportunity to put the practices you’ve honed to work, such as CI, CD, infrastructure as code, build automation, and, the most universal tool of all, scripting.

You’ll walk away from this talk with a new perspective on documentation. It will no longer be just a writing thing, but rather a challenging engineering problem that you have the skills to help solve.

First, ensure you have the following installed:

1. Node.js >= 4.2 ^[1]

2. Yarn

   $ npm install -g yarn

3. Gulp (command line interface only)

   $ npm install -g gulp-cli

4. Ruby >= 2 ^[2]

   $ rvm use 2.4.2 --install

5. Bundler

   $ gem install bundler

Next, install dependencies (if you ran the generator with the --skip-install switch):

Finally, build and serve the presentation!

You can view the presentation in your browser at the URL displayed in the console.

By default, the preview server runs on port 8000. To change this default, you can assign a different number to the PORT environment variable:

To build the presentation without starting the preview server, use:

In both cases, the files are built into the dist directory. You can view the slides outside of the local preview server by navigating to dist/index.html in your browser.

The Gulp build includes a task to publish the presentation to GitHub Pages.

First, make sure you have initialized the project as a git repository and linked it to a GitHub project. The task assumes that the git remote named origin points to the repository on GitHub.

Now you can build the presentation and publish it to GitHub Pages using:

The files in the dist directory end up in the gh-pages branch in the repository on GitHub. From there, they can be viewed in a browser from anywhere on the web.