Toolchain families

A toolchain is a description of all the tools, components, and processes used to build documentation.

For examples of an individual toolchain and a toolchain comparison, see this article: Comparing doc tools: Stop doing the apples-to-oranges thing

A toolchain family is a description of a type of toolchain. Although every organization has slightly different practices, there are a handful of common approaches that most people would recognize. I listed common toolchain families here because it's helpful to understand why an organization would pick each of them – even if you wouldn't expect to use some of these yourself.

The tools chosen by an organization tend to correspond to requirements. They may have been chosen to solve a particular problem or address an organizational need. When you think about changing a toolchain, ask why the current tools were chosen in the first place because the requirements haven't necessarily changed. In other words, if you use a new tool, it might have to meet the same requirements that the old tool met, in addition to the things that you want it to do.

Here are the most common toolchain families:

Docs as Code
Structured markup (e.g. the DITA approach. It's good to remember that Docs as Code isn't the only type of toolchain that involves automation.)
Desktop publishing (The unstructured FrameMaker approach)
Wikis (Confluence)
Custom applications (Stripe docs)

Docs as Code

Description: This approach adapts the tools and processes of code development for documentation, so that developers will be more likely to contribute to documentation. It does away with the tools typically favored by technical writing teams and replaces them with simple text editors or IDEs and Git.

The essentials: Docs as Code


Main use cases	Strengths	Limitations
Developer-facing docs. Written by developers. Published on the web. Uses an automated build to produce documentation. Stores documentation source code in the same repo as the code, or very close to it. Open source.	Allows developers to contribute to documentation by allowing the use of tools familiar to developers. Initially inexpensive to deploy because tools are free and already in use in the same organization. Moves away from the need for specialized tools. Easy to incorporate into the engineering workflow, so that developers can write the documentation. Allowing developers to write documentation reduces the cycle time involved in updating the docs.	Markdown and other plain-text markup languages are not the best when you have a lot of tables, and tables are commonplace in technical documentation. Unlike XML, Markdown files are not required to be valid as a condition of processing, so invalid markup can lead to garbled output, without warning. This combined with finicky tables and bulleted lists can lead to unsatisfactory results. Open-source tools often (but not always) lack the features that come with more advanced tools and mature markup languages. (For example: search, metadata tagging, and easy reuse.) Sometimes developers are needed to reproduce features that already exist elsewhere. PDF output is often not included. Automation requires ongoing support and maintenance from specialized developers--not a realistic option for small writing teams that lack a dedicated tool developer.

Docs as Code: common components of this toolchain family


Layers	Examples of commonly used tools and components
Deploy	Deployment options are numerous and are similar across most toolchain families. For automated docs, deployment from a repo is standard; within the docs as Code family there are specialized services like Read the Docs, Netlify, and SwaggerHub. Also deployment to simple delivery services like Google Content Delivery Network or Amazon S3 buckets. Docs can be uploaded to larger systems like Salesforce and Zendesk.
Build	Static site generators like Jekyll and Hugo. For OAS3 specifications, Swagger UI, Redocly, and others.
Transform
Automation	Services like Jenkins, GitHub Actions, and GitLab CI/CD.
Source code management	Source code management tools, like Git and Perforce. Repositories like GitHub, GitLab, and Bitbucket.
Editing tools	Plain text editors and IDEs. (Whatever the developers are already using to write code.)
Markup language	Simplified markup languages like Markdown, ascii-doc, and reStructured Text. OAS3 specification files, in YAML or JSON.

Structured markup

Description: Structured markup is the original home of programmatically generated documentation. Years before the docs-as-code approach came along, DITA and DocBook were invented specifically for technical documentation.

The essentials: structured markup


Main use cases	Strengths	Limitations
Automated layout. Programmatically builds large projects, with potentially thousands of topics. Translation. Creates efficiency by allowing automated layout of translated text, so that changes in length don't result in costly manual resetting of text that would be necessary on some systems. Single sourcing/reuse. When files become a component in multiple publications or multiple forms of output, this type of toolchain enables the reuse of a single unit of content in many places.	Automated builds for voluminous documentation sets. Continuous integration, with docs building whenever there is a commit on the main branch in SCM. Validation. Builds break when the DITA is invalid, preventing potentially flawed documentation from getting published. Consistency. Can be used to enforce consistency of content and structure in an automated way. (For example the schema might require that a topic begins with a short description.) Easier to translate than some formats, because you can send one small topic for translation, rather than the entire document. Also, you don't have to reflow a layout when translating because the layout is automated. Reuse features are better and more varied than with other toolchains. Conditional formatting. Elements can be tagged so that they only appear in certain output formats (i.e. PDF only) or in certain versions of the docs (For example, Windows, but not macOS). Conditionalized text can be managed down to the level of one word (or one character if you want). Metadata tagging. Content can be tagged to show that it is designed for certain types of users or for certain groups. Creating dynamic links across topics and between documentation sets, links that don't break if the site is reorganized or moved.	The editing tools and markup languages take time to learn. Developers may reject these in favor of plain text in a text editor or IDE. Specialized tools require a license for every user, which can be a barrier. Automation requires ongoing support and maintenance from specialized developers--not a realistic option for small writing teams that are starved for resources.

Structured markup: common components

There are two distinct approaches. One involves a text editor like Oxygen, SCM like Git, and a publishing solution. The other approach involves an all-in-one component content management system (CCMS), which contains everything from the editing environment to version management to transformation. Sometimes even deployment and hosting of the published content.


Layers	Examples of commonly used tools and components
Deploy	Deployment options are numerous and are similar across most toolchain families. For automated docs, deployment from a repo is standard. Also deployment to simple delivery services like Google Content Delivery Network or Amazon S3 buckets. Docs can be uploaded to larger systems like Salesforce and Zendesk.
Build	For desktop builds, the editing tools also create output. (Oxygen, Framemaker, and XMetal) For automated builds, DITA-OT and XSLT custom transforms can be used. A built-in publishing engine is used in the case of a CCMS, like Ixiasoft, Paligo, or Adobe Experience Manager.
Transform
Automation	Services like Jenkins, GitHub Actions, and GitLab CI/CD.
Source code management	Git and other SCM. Github and similar repository services. Built-in version control, in the case of a CCMS, like Ixiasoft, Paligo, or Adobe Experience Manager.
Editing tools	Markup-aware text editing tools, like Oxygen, Framemaker, XMetal, and Madcap Flare. Built-in editing environment, in the case of a CCMS, like Ixiasoft, Paligo, or Adobe Experience Manager.
Markup language	Structured languages like DITA, DocBook, XHTML, and S1000D.

Desktop publishing tools

Description: Desktop publishing tools with binary file types might be relied on where PDF is a requirement, especially if there's a need for PDF with a slick layout. PDFs are a mandatory deliverable for certain industries, including medical devices, pharmaceutical companies, certain automotive applications, and government or military contractors. PDF output may be required by law, by a regulatory body, or by a contract with a customer.

A team that uses desktop publishing in a documentation set out of necessity, might have other docs containing APIs and SDKs that call for a different approach – this can lead to a complex situation when choosing tools. The team might be best served by an environment where they're allowed to use different tools and processes for different sets of documentation.

The essentials: desktop publishing


Main use cases	Strengths	Limitations
Documentation where PDFs are required. (This category existed before the advent of HTML documentation.) Publications that require precise layout, which can't be delivered by automation, like a slick, well-designed PDF.	PDF output. Precise, pixel-perfect layout. Conditional formatting, to create multiple editions of a document for slightly different products or platforms.	Web output can be difficult to produce and may look like a PDF. Proprietary file formats, usually binary, restrict users to one tool and aren't compatible with many SCM systems.

Desktop publishing: common components of this family


Layers	Examples of commonly used tools and components
Deploy	Deployment options are numerous and are similar across most toolchain families. Deployment to simple delivery services like Google Content Delivery Network or Amazon S3 buckets. Docs can be uploaded to larger systems like Salesforce and Zendesk.
Build	For desktop builds, the same tool used for editing performs the build. (Word, FrameMaker, InDesign.) Build and transform can be automated through proprietary services like FrameMaker Publishing Server, InDesign Server, and Adobe Experience manager. Automated builds are less common with binary file types.
Transform
Automation	Build and transform can be automated through proprietary services like FrameMaker Publishing Server, InDesign Server, and Adobe Experience manager.
Source code management	Cannot be stored in typical SCMs (like Git and Perforce) because they do not handle binary files well. Can be used with a component content management system that offers version support.
Editing tools	Word, unstructured FrameMaker, InDesign
Markup language	NA

Wikis: the all-in-one solution

Description: A wiki is a top-to-bottom solution that provides everything from the editing environment to deployment.

The essentials: wikis


Main use cases	Strengths	Limitations
Frequently used for internal documentation.	Easy collaboration. Allows anyone in the organization to contribute content.	PDF options may be somewhat limited. Developers may be just as avoidant of wikis as other writing tools.

Wikis: common components of this toolchain family


Layers	Examples of commonly used tools and components
Deploy	All-in-one systems offer everything from the editing environment to deployment of the final product. For example: Confluence or MediaWiki (Used by Splunk to create Ponydocs.)
Build
Transform
Source code management
Editing tools
Markup language

Custom-made documentation apps and developer portals

Description: Stripe developed their own documentation site with enough functionality that it could be considered an application in its own right. For example, users can sign into the Stripe docs and test API calls on their own data. Salesforce's Trailhead is another example; learners can earn badges by completing training on the site.

(There are other large documentation efforts to create in-house documentation tools, like Google's g3docs (see this talk by Riona MacNamara), and Twitter's DocBird. These are essentially docs-as-code on a large scale. )

The essentials: custom documentation apps


Main use cases	Strengths	Limitations
Adding advanced functionality to the documentation, to improve customer experience.	Can be well-aligned with user needs.	To create a proprietary in-house docs app requires a large, ongoing commitment of developers and possibly a product management team.

Stripe docs were open sourced as Markdoc.