Validation and quality control
Validate technical documentation before delivery: run validation in parallel with writing, track every change request through a CMS workflow or a ticketing system, and use comparison tools to review updates reliably.
Definition
Section titled “Definition”Content must be validated before delivery. This may seem obvious, but it requires the involvement of the people in charge of validation from the outset. Ideally, the validation phase takes place in parallel with the creation phase: early modifications are less costly.
Validating in parallel with writing shortens the publication timeline.
Creation and validation workflow
Section titled “Creation and validation workflow”A process for creating and updating technical documentation that relies solely on human memory is unreliable. A technical writer may be tired, unwell, on vacation, overwhelmed with information, or may have left the company. Communication between two people can also fail or be misunderstood. Humans have created tools to compensate for these weaknesses, although they remain creative, unlike machines.
A process based on human memory is unreliable.
Given this situation, we need an information management system for the evolution of documentation that is tolerant of human error. This means either implementing workflows under a CMS (Content Management System)A tool that adds workflow and file-locking to content management, at the cost of reliability trade-offs compared to plain version control.View in glossary →, or using the ticket management system of the documented product.
Workflows under a CMS
Section titled “Workflows under a CMS”The main functions of a CMS are metadata management, workflows, and traceability.
The product’s ticket management system
Section titled “The product’s ticket management system”The ticket management system used to handle new features of the documented product (e.g., Jira) takes each documentation request through its life cycle:
- creation of a ticket by a developer,
- implementation of the ticket by a technical writer,
- closure of the ticket by the ticket creator,
- publication of documentation when all critical tickets have been closed.
The ticket workflow moves each request through to publication.
Requirements for any tracking system
Section titled “Requirements for any tracking system”Whatever the tracking system:
- Traceability. It must offer full visibility and traceability of changes made to technical documentation (what, who, when).
- A single, exhaustive system. It must centralize all requests for changes to technical documentation.
- One track per language. If the document is available in several languages, each ticket must be duplicated for each language or, in the case of a CMS, each language must correspond to a separate workflow.
Trade-offs
Section titled “Trade-offs”An enterprise content management tool such as Alfresco may seem like an attractive way to set up workflows, at least on paper. In reality, however, such a solution can be cumbersome. It is also incompatible with certain Source formatThe format content is authored in, as distinct from the target format it's published to — the recipe versus the dish.View in glossary → based on modular, non-monolithic documents and version management software (the Componize project, however, proposes managing DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → projects within Alfresco).
It remains imperative to set up validation stages throughout the project.
Comparing versions
Section titled “Comparing versions”Combined with a version management system, comparison tools are very useful for validating updates. For example, a “tagged” version of a DITA XML project and the current version can be exported in RTF format, then compared in a word processor. This is far less tedious than a manual comparison. Comparing information modules directly in the version management system is not sufficient, as they are merely the “building blocks” of the final document.
Pull requests and automated checks
Section titled “Pull requests and automated checks”When documentation sources are text files in Git, the Pull requestA request to merge a branch's changes into the main line, presented as a reviewable set of differences: reviewers comment, automated checks run, and approval is recorded before publication. GitLab calls it a merge request.View in glossary → provides the traceability described above (what changed, who changed it, when, and who approved it) and version comparison becomes a plain git diff, rather than an export to a word processor. Validation then splits into two complementary layers:
- Automated checks run on every change before it is merged: the build itself, link checking, metadata and structure validation. They catch mechanical errors consistently and cheaply. See the CI/CD pipeline example.
- Human review covers what no tool can check: technical accuracy against the product, and editorial quality. See the review workflow example, the technical review checklist, and the documentation quality checklist.
Content drafted with AI assistance goes through the same two layers; it does not need a separate process, but it does need the human review.