Skip to content
Olivier CarrèreTechnical writing practice

Integrating documentation into development processes

Concept
GitDocs-as-codeCI/CD

Learn why technical documentation should be released, versioned, and quality-controlled alongside the product, using text formats like DocBook, DITA XML, and reStructuredText.

, 3 min read

View as Markdown

Definition

Section titled “Definition”

Documentation is part of the software. Supplied with the product, it must:

  • be released simultaneously with each software version, avoiding outdated guides at launch;
  • follow the same life cycles, from initial feature design to staging, tagging, and release;
  • be subject to the same production and quality control processes, including automated linting, peer review, and continuous integration.

The integration pipeline

Section titled “The integration pipeline”

Integrating documentation into development requires a connected pipeline where content moves through the same stages as application code:

Integrating modular documentation into the development pipelineFlowchart showing modular documentation sources fed by bug tracking, connected to version control, and profiled into PDF, HTML, JavaHelp, and ePUB outputs.Bug trackingModular documentationsourcesVersion controlProfilingPDFHTMLJavaHelpePUB

Modular documentationContent built from small, reusable, standalone units (topics or modules) assembled on demand, rather than authored as monolithic documents.View in glossary → sources in text format

The pipeline links four main stages:

  1. Issue and bug tracking: Documentation tasks, missing TopicThe smallest autonomous, titled unit of information in DITA XML, typed as concept, task, or reference and assembled into documents via ditamaps.View in glossary →, and error reports are logged in the same issue tracker as code changes, aligning technical writers with the engineering backlog.
  2. Modular text sources: Content is authored in plain-text formats (such as MarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary →, DocBookA semantic XML markup language for technical documentation, organized in books, chapters, and sections rather than typed topics. It predates DITA XML and is the usual point of comparison when choosing a structured format.View in glossary →, DITA XML, or reStructuredTextA plain-text markup language from the Python ecosystem, richer than Markdown (directives, roles, cross-references), and the native source format of the Sphinx documentation generator.View in glossary →) and split into modular topics rather than monolithic documents.
  3. Version controlRecording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code.View in glossary →: Source files reside in a version control system like Git or Subversion, enabling parallel BranchA parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time.View in glossary → development, diff reviews, and safe rollbacks.
  4. Profiling and automated delivery: Build engines apply conditional filtering (profiling) to compile targeted deliverables across multiple formats-such as HTML, PDF, JavaHelp, or ePUB-from a single source base.

Traditional vs. integrated documentation

Section titled “Traditional vs. integrated documentation”

The shift from isolated desktop publishing to an integrated pipeline resolves longstanding synchronization and quality bottlenecks:

DimensionTraditional documentationIntegrated documentation (Docs-as-codeTreating documentation like source code: text-based formats, version control, code review, and CI/CD, rather than a separate publishing process.View in glossary →)
Storage formatProprietary binary files (Word, FrameMaker, InDesign)Plain-text formats (Markdown, XML, reStructuredText)
Version controlShared network drives or manual file copiesVersion control systems (Git, Subversion)
CollaborationSequential file locks, prone to overwritten editsConcurrent branches, pull requests, and peer reviews
PublishingManual formatting, manual export per deliverableAutomated CI/CD (continuous integration and continuous delivery)Automation that checks every change as soon as it is submitted (continuous integration) and publishes the result once the checks pass (continuous delivery). In docs-as-code, a CI/CD pipeline builds the documentation, runs tests such as link and schema checks, and deploys the site.View in glossary → pipelines and programmatic profiling
Release cadenceFrequently delayed weeks or months behind the codeSynchronized and released alongside the product build

Key principles

Section titled “Key principles”

Ideally, an integrated documentation workflow should meet three core criteria:

  • No vendor lock-in: Independence of format and content editor. Because sources are plain text, writers can edit them with any tool-from simple text editors to full-featured IDEs-without proprietary software dependencies.
  • Free and open publishing channels: Toolchains built on open standards and open-source compilers ensure that documentation builds can run anywhere, including automated CI/CD servers.
  • Fully automated layout: Separation of content from presentation. Formatting rules are defined centrally in stylesheets and templates, eliminating manual desktop publishing adjustments.

Why text formats make integration possible

Section titled “Why text formats make integration possible”

Until a few years ago, the only tools available to deliver quality deliverables in PDF or HTML relied on binary and proprietary formats that didn’t integrate well with development teams’ version control systems.

As a result, technical documentation could not meet the same quality and time-to-market requirements as the products.

DocBook, then DITA XML, and reStructuredText have changed all that: these text formats can be edited with any type of program, from a simple text editor to a graphical IDE, integrating perfectly with Subversion, Git, or any other version control system.

Putting integration into practice

Section titled “Putting integration into practice”

To apply these principles in production, consult the following resources from the practical toolkit:

Section titled “Related articles”
Section titled “Related reading”