Docs-as-code
Modern tech writing has evolved to treat documentation like code in how it’s versioned, reviewed, tested, and deployed. While I began my career watching Microsoft Word struggle with 500+ page documents, I’ve learned first-hand that delivering high quality documentation at scale means having high quality tools and processes.
Fortunately, there’s no need to reinvent the wheel. Treat the docs like code!
Git
Whether working alone or on a team, proper version control is a must.
Feature branch workflow
As a general rule, main branch always contains production-ready code. This way, you can quickly release new docs without worry of it containing unfinished work or errors that’ll break your site. Feature branches off of main contain in-progress work for upcoming releases. I prefer to scope feature branches at the Epic or Feature level and merge completed child tickets into them. How you structure your tickets informs how you structure your branches, but keep those feature branches short-lived!
Feature branching is more straight-forward the more "agile" a company’s release schedule is. In other words, if a company releases a feature once it’s complete, the feature branch containing the docs is simply merged to main come release time. However, if a company prefers a longer release runway (cough! waterfall! cough!), I’ll create a release branch off main to merge completed feature branches into.
Branching like this makes writing release notes for service packs and hotfixes simple, as these docs are just another feature branch.
Feature branch naming conventions
I prefer to name branches using ticket IDs, for example feature/id-123. Descriptive names can become confusing, vague, or even inaccurate as development evolves. The associated ticket ID serves as a breadcrumb to the source of truth.
This isn’t the most alluring naming convention, but sometimes clarity is better than cleverness.
$ git branch
* main
feature/jira-123
feature/jira-456
feature/jira-789
release/v1.1.0
hotfix/v1.0.4Pull requests
Before merging, I like to test and peer review my docs as part of a Pull Request. If possible, I’ll deploy a feature or dev branch to a staging environment and share with internal shareholders before the release.
Content reuse
Docs-as-code encourages tech writers to borrow from the coding concept of modular programming. This term describes how programmers separate code into independent files depending on the purpose it serves. This approach leads to less manual work and makes managing code easier. Why write something three or four times when you can write it once and reuse it? This is transferrable to docs, of course.
Writing docs that are more flexible and narrowly scoped may take some initial planning, but the approach is ultimately more efficient, not to mention less of a headache to manage. Proper content reuse also creates consistency for readers, making the docs easier to read.
Examples depending on software
Content reuse goes by different names depending on the software I’m using, but the concept remains the same. Here are a few examples.
In MadCap Flare, I can use a snippet to remind users where to view their user permissions, for example. This is helpful when a task requires a specific permission. If the path to this location changes, or I want to update wording in this blurb, I only need to update the snippet once.
<MadCap:snippetBlock src="../resources/snippets/view-user-permissions.flsnp" />In Hugo, I can create a custom shortcode with this information and reference it across the docs.
{{% view-user-permissions %}}When writing with AsciiDoc in Antora, I can use the include:: directive to display content from a partial.
include::partial$/view-user-permissions.adoc[]Topic typing
Topic typing categorizes content based on the purpose it serves as well as its style and theme. This approach scopes writing into potentially reusable sections. Generally, I prefer to organize content into three basic categories: concept, task, or reference.
-
Concept: used when introducing or explaining an idea, like the overview of a complex feature
-
Task: used when instructing user action, like enabling a feature within a product
-
Reference: used when providing a large amount of scannable information, like tabular data about compatibility
Dedicating a page to a specific topic type is enough modularity sometimes. For increased reuse potential, I’ll make each piece of content within a page more modular, if desired. Regardless of how modular I go, I make sure I’m consistent in how I template each topic type. This consistency enables me to plug-and-play content as needed.
= Topic xyz
include::topic-xyz-intro.adoc
include::topic-xyz-prerequities.adoc
include::concept-x.adoc
include::concept-y.adoc
include::concept-z.adoc| Structuring content for reuse is easier to do from the start but don’t feel like you have to structure everything for reuse. Discuss with your team (or yourself) to determine how modular your docs should be. |
Reviews
Docs are best when they’re collaborative. And the most fruitful collaboration often takes the form of reviews. Tech writers usually aren’t the expert on the subject they’re writing—for this, there’s the subject matter expert (SME) review. And authors usually aren’t the best editors of their own work—for this, there’s the peer review.
Reviews might look different depending on personal preference and the software used. I’ve conducted reviews of plain text docs in GitHub as part of a Pull Request, as well as in exported Word docs uploaded to SharePoint with the Track Changes feature turned on.
As is the rule with all collaboration, work with others to find the best compromise.
SME review
This review involves working with a SME to ensure technical accuracy, proper order of operations, and prerequisites, for example. Tight feedback loops between a tech writer and SME is ideal. As a courtesy, ask the SME how they’d prefer to handle reviews and accommodate accordingly. Some prefer a meeting while others only have time for emails or SharePoint files. Efficient use of a SME’s time is crucial as experts are often called to many tasks.
Complete SME reviews before requesting peer review.
Peer review
Once the SME signs off on the docs, tech writers can review each other’s work. Peer review considers style guide adherence, proper information architecture, and consistency in tone, grammar, and usage. Always communicate feedback professionally and consider the author’s feelings. Peer review isn’t a free pass for ruthless criticism!
Complete this review as part of a GitHub Pull Request.
Feature review
Once a feature is nearing feature complete status, it should consider the opinion of other stakeholders (Product Management, Engineering, Professional Services, Support). This review takes into account higher-level feedback from a wider audience and serves as a jumping off point for training. You’ll likely receive lots of out-of-scope feedback from this review, so create tickets in your backlog and plan accordingly. Not everything requested in this review can make the initial release.
Testability
Tech writers don’t just write the docs. They should test them too!
Linters
Validating documentation doesn’t need to be purely subjective. Tools like Vale deliver data around style guide adherence and readability. Vale lets you customize existing style guides and create your own rules to reflect your organization’s preferences. It’s a very powerful tool.
Acceptance criteria
Clear, demonstrative acceptance criteria helps writers know when they’re done with a ticket. Writing can always improve, but that doesn’t mean the work is done in one fell swoop. Instead, write acceptance criteria that captures the purpose and scope of the ticket, then validate against it.
| Keep your AC action-oriented from the user perspective to make testing easier. |
Here’s a couple of examples to show what I mean:
Document feature xyz
-
upgrade instructions contain new required steps identified in Ticket-123
-
upgrade instructions contain an IMPORTANT admonition clarifying that this doesn’t affect UK clients
You may see these examples on another page. I’ve reused them with the includes:: directive! In fact, this note admonition is its own file called note-about-ac.adoc and is referenced on multiple pages. 😊
|
Reviews
SME and peer reviews serve as catch-all tests for what escapes linters and acceptance criteria. This is the arena for "I think this paragraph is confusing" or "I would word this differently" type of feedback. Tech writers are human after all, writing documentation for other humans, so docs should consider these subjective criteria, too. Effective tech writers must develop the ability to synthesize murky (and sometimes conflicting) feedback into clear docs.