Learning Asciidoc

I’ve been spending time boning up on technical writing skills over the past few months. As a teacher of professional and technical writing it’s important for me to be able to explain not just the role of language but also of technology in technical writing. Beyond that, readers of my blog are aware of my obsession with learning, technology, and learning about technology.

The specific skills I’ve been practicing and developing relate to my interest in the Docs as Code philosophy. According to Write the Docs:

Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:

• Issue Trackers
• Version Control (Git)
• Plain Text Markup (Markdown, reStructuredText, Asciidoc)
• Code Reviews
• Automated Tests

This means following the same workflows as development teams, and being integrated in the product team. It enables a culture where writers and developers both feel ownership of documentation, and work together to make it as good as possible.

Specifically, I decided to learn AsciiDoc and AsciiDoctor and how these tools enable single-source authoring across an array of output formats. While I’m very familiar with some fundamental principles of Docs as Code from my years using Jekyll and Hugo, it was fun finding ways to use AsciiDoc’s affordances–like attributes and conditionals–to create sample documents that could output quite differently for different genres and formats, including print. As a small-scale project, I rewrote and improved the documentation for Little Ghost, my Hugo theme, using AsciiDoc. You can find that documentation here.

Currently, I’m working my way through Tom Johnson’s “Document APIs: A Guide for Technical Writers and Engineers.” I’ll be putting together a post (or, more likely, multiple posts) on working through this tutorial. It’s enough to say that it’s challenging (the productive, fun kind) and really engaging.