I swear I don’t just love this stack because of the title it gives me. I do admit “Hyde” wouldn’t have made it into the title if it didn’t just sound so good, but it’s also a nice theme, as you can see.

In any case, that’s what’s under the hood of this site. All pages and posts are written in AsciiDoc dynamic markup, converted to HTML by the Asciidoctor rendering engine, built into a proper site by Jekyll static generator with a lightweight theme called Hyde giving the pages structure and style. Then served on GitHub Pages.

I’ve been working with Jekyll and Asciidoctor for well over a year now, and I am confident that they are robust, pliable utilities that can solve a very wide range of technical documentation problems. This is especially true when you consider the broad range of Asciidoctor output.

In this blog, I will journal some of my technical experiments in documentation tooling, much of it around Asciidoctor and my own free and open source tool, LiquiDoc. All of this tooling is FOSS, and it’s all written in Ruby, which I started learning some months back in order to hack a complex docs build toolchains. Now I’m looking for new projects and challenges, which i hope to trace here.

Not that I’m hacking or extending it, the other major tool all of this depends on is Git.

If you’re a technical documentarian of any kind, consider checking out my book Codewriting. I’ve set up an RSS feed, and I’ll be posting links on my nascent Twitter account (@_codewriter) as soon as I get my shit together.

By my count, there are seven major types of user interfaces (UI) that developers make and tech writers document. I have found a few lists of computer interface types, most of them paltry. None speaks from a documentarian’s point of view, but lack of coverage has never meant something is not actually important to do technical writers. We’re often just too busy writing about our products to stop and explore just how we do that.

Nevertheless, at risk of stirring up controversy, let me take a stab:

You may be tempted to add to these top-level categories — and the Wikipedia article would encourage this — but I challenge you to help me merge and reduce, if possible.

I don’t know why I find this taxonomy comforting, but it helps me to approach each type of interface with its particular attributes front of mind.

Interface types are often associated with audience types. If I’m documenting a CLI, I know it’s not for my father. In fact, if my father is the product’s audience, we know a CLI is not the right interface choice. Aside from unforgiving syntax, the command line lacks visualization and only minimally abstracts underlying logic and routines. This makes the CLI a non-starter for huge swaths of less technically inclined users, as well as less frustration-inclined geeks.

While command-line interfaces are considered the most intimidating, they are by no means the most complex. In fact, the list of UI types above reflects my sense of the ascending order of potential complexity. The less burdensome the interface seems, the more open-ended it is, and thus the more complicated it would be to fully capture the range of its utilization.

Imagine the potential complexity of a natural language interface. Most limitations of Siri and Alexa are not in the interface, but in the intelligence. The range of commands such systems can already distinguish make them spectacularly open ended.

Drastically more complex than any mere language-based interface is VR, which can incorporate natural language commands, kinetic interface techniques, and eventually advanced brain and neural interfaces. One can almost imagine VR so immersive the user cannot distinguish the digital world from the natural world. Such an interface would be so intuitive, in the truest sense of that term, it would be essentially impossible to document.

Or maybe the instructions could be captured in one simple command: “Act naturally.”

Think about your current product. Whether you have a dedicated technical writer/docs team or your developers self-document the product, which domain is considered the canonical source of truth over product features? Let me put it another way. If I asked you to be absolutely certain that the default setting of a particular configuration property is true or false — not the stated value but the actual out-of-the-box value, and not what it’s supposed to be but what it actually is — where would you turn: the codebase or the docs?

If your answer is, “We keep our docs in our codebase, sucker!”, you definitely earn points with me. But you still have not addressed the spirit of my question.

Which part of your codebase contains the canonical answer to my question about that default setting?

Here you are probably wondering if I’m crazy, some megalomaniacal tech writer who doesn’t even understand programming. Surely the answer must be the product code. No matter which one we consider the primary source, no matter how badly some tech writer might wish that “the docs are always right” or some such fantasy, the product source defines the answer, and therefore it must be the prime source of truth.

What if it doesn’t need to be that way? There is only one way your product’s backend, API, user interfaces, and documentation will all reflect the same information about every detail of your product. That way is to single-source all reference matter, drawing on that prime source every time you generate a dependency library, an interface, or a document — basically, every time you build.

For developers, all this really means is self-consciously organizing “small data” related to the product in universally accessible formats such as JSON, YAML, XML, or CSV, rather than native data structures, whenever possible. Native structures can then be built from these prime sources at build time or runtime.

This manner of operating is more challenging for the documentation side, as currently even the more sophisticated documentation systems provide very limited support for deriving usable structured data from external sources. Unconventional tooling is required to generate and serve tables or pages from those cross-platform data structures, but these tools exist and are becoming accessible. And the benefits can be enormous.

The case I am making is that because there is no room for divergence of the product’s documented behavior and its actual behavior, every human-dependent step between the product code and the generated docs is a chance for divergence.

We get it right more often with APIs, because we tend to source API docs very much within the product codebase. When the codebase and the interface are more directly related and less abstracted, documentation pairs nicely with its underlying code. There are still ways to improve overly robotic API docs, but others are tackling this subject more concertedly than I. (For instance, techcomm blogger/guru Tom Johnson is delightfully obsessed with API docs, as is the network API the Docs.)

For end-user-facing interfaces and docs, as well as for docs that go beyond strict reference format — that is, exceptional docs — smarter tooling is needed to ensure currency and accuracy.

It may seem like I am writing the writer out of the documentation story, but I intend no such thing. Managing these details is not necessarily a huge part of our job, though it is among the more perilous and tedious. There’s a decent chance your bosses and subject matter experts already assume you have some great system or keep docs updated in your sleeps somehow. It’s where we can be most objectively wrong, and where we are most workflow dependent, hoping that the communications between us and SMEs is bug free.

And this makes sense beyond the engineering and support teams, if you think about it. Not only do interfaces and instructions have to correlate to the application’s existential truths, so do legal docs that explain users' legal rights and obligations pertaining to your product. These rules may vary depending on which version they are using, or from where they’re accessing your cloud. End user license agreements, enterprise software service contracts, system permissions requests, and privacy policies can be extremely difficult to coordinate across jurisdictions and product versions. Yet it is critical that any promises made in them are perfectly consistent with their associated product version.

Is anybody drawing product data and docs content from the same data sources? I am eager to learn more about how this is handled at different shops, as I intend to make it a central feature of the strategy I’m developing, unless I learn it is too difficult to implement in too many circumstances. So I’d love to hear struggles as well as success stories.

After six months of writing in private, I released a draft of my book-in-progress about collaborative software documentation practices and tools during the “Writing Day” pre-conference that kicked off “Write the Docs Portland 2017”. I will however be finishing the book in public, hopefully with contributions from others in the field.

Codewriting is my attempt at learning in public, documenting my observations of the field and my approach to problem solving as a self-certified DocOps hacker.

After a recent career shift, I found myself as a former developer employing a cutting-edge methodology in technical documentation, and eventually writing software to build better docs. Now I’m excited to start sharing with the broader software development and documentation community the lessons I’ve learned along the way.

One of those lessons is to operate collaboratively and let subject-matter experts (SMEs) contribute directly to the common wisdom in a shared source repository. In the case of Codewriting, SMEs are my fellow docs hackers and tech writers solving remarkably difficult tooling, workflow, and content problems in forward-thinking ways. In keeping with this observation, such people are strongly encouraged to fork and contribute to the book draft I’ve set forth, writing in public alongside me.

And everyone is invited to begin taking advantage of the book’s content (in draft form, for now) as well as the rudimentary (alpha pre-release) build tooling used to compile the document source into PDF and HTML. Codewriting is its own self-contained source codebase and build platform; anyone can clone or download the repo and use contained Ruby scripts to build the book from source. These same AsciiDoc-centric tools are featured in many of the book’s lessons.

As a former mediocre developer and modestly successful professional writer, in 2015 I found writing about a sophisticated, cutting-edge Big Data IT ops enterprise platform to be my domain. I was overjoyed to find myself writing Rocana’s product documentation using the same principles and processes employed by the engineers writing code. I sit on the Engineering team as a valued contributor, and my Reference Guide source code sits in the product codebase, as valued content.

I believe this system lets me do better work with less frustration and perhaps even fewer errors. What’s more, I think I can help teach it to programmers who want to write and maintain better docs, as well as tech writers who want to work more programmatically, perhaps in closer proximity to engineers.