# Validation and quality control

> **Note**
>
> Technical writing materials must undergo rigorous quality control before being sent to their intended audiences.

## Definition

Content must be validated before [delivery](https://docs.redaction-technique.org/en/tech-writing-process/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.

```mermaid
%%{init: {"themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif", "taskBkgColor": "#f1f5f9", "taskBorderColor": "#64748b", "taskTextColor": "#0f172a", "taskTextOutsideColor": "#0f172a", "taskTextLightColor": "#0f172a", "taskTextDarkColor": "#0f172a", "sectionBkgColor": "#e2e8f0", "sectionBkgColor2": "#f1f5f9", "gridColor": "#64748b"}}}%%
gantt
    accTitle: Serial or parallel validation of the writing phase
    accDescr: Gantt chart comparing a serial process, where validation only starts once writing is complete, and a parallel process, where validation starts as soon as the first modules are written, shortening the publication timeline.
    dateFormat YYYY-MM-DD
    axisFormat %d
    tickInterval 1day
    section Serial process
    Writing               :s1, 2024-01-01, 1d
    Validation            :s2, after s1, 1d
    Publication           :s3, after s2, 1d
    section Parallel process
    Writing               :p1, 2024-01-01, 1d
    Continuous validation :p2, 2024-01-01, 1d
    Publication           :p3, after p1, 1d
```

**Validating in parallel with writing shortens the publication timeline.**

## 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 formats based on modular, non-monolithic documents and version management software (the Componize project, however, proposes managing DITA XML projects within Alfresco). It remains imperative to set up validation stages throughout the project. 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.

## Creation and validation workflow

A process for [creating](https://docs.redaction-technique.org/en/tech-writing-process/content-creation/) 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.

```mermaid
%%{init: {"themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif", "lineColor": "#64748b", "mainBkg": "#f1f5f9", "textColor": "#0f172a"}}}%%
ishikawa
    Unreliable documentation process
        Writer
            Fatigue
            Illness
            Vacation
            Forgetting through information overload
            Leaving the company
        Communication
            Poor information flow
            Being misunderstood
```

**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),
- using the ticket management system utilized to handle new features of the documented product (e.g., Jira):
  - 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.

```mermaid
%%{init: {"themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif", "cScale1": "#e2e8f0", "cScaleLabel1": "#1e293b", "cScaleInv1": "#3b82f6", "cScale2": "#e2e8f0", "cScaleLabel2": "#1e293b", "cScaleInv2": "#3b82f6", "cScale3": "#e2e8f0", "cScaleLabel3": "#1e293b", "cScaleInv3": "#3b82f6", "cScale4": "#e2e8f0", "cScaleLabel4": "#1e293b", "cScaleInv4": "#3b82f6", "cScale5": "#e2e8f0", "cScaleLabel5": "#1e293b", "cScaleInv5": "#3b82f6"}, "kanban": {"sectionWidth": 260}}}%%
kanban
    created[Created]
        t1[New feature to document]@{ ticket: 'DOC-142', assigned: 'Developer', priority: 'High' }
    inprogress[Writing in progress]
        t2[Update the installation guide]@{ ticket: 'DOC-138', assigned: 'Technical writer', priority: 'Very High' }
    closed[Closed]
        t3[Add a configuration example]@{ ticket: 'DOC-121', assigned: 'Technical writer' }
    published[Published]
        t4[Rework the troubleshooting section]@{ ticket: 'DOC-098' }
```

**The ticket workflow moves each request through to publication.**

The main functions of a CMS are as follows:

- metadata management,
- workflows,
- traceability.

Whatever the tracking system, it must offer full visibility and traceability of changes made to technical documentation (what, who, when).

This system must be unique and exhaustive: it must centralize all requests for changes to technical documentation.

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*.

## Related articles

- [Project definition](https://docs.redaction-technique.org/en/tech-writing-process/project-definition/)
- [Gathering information](https://docs.redaction-technique.org/en/tech-writing-process/gathering-information/)
- [Source format](https://docs.redaction-technique.org/en/tech-writing-process/source-format/)

---

Source: https://docs.redaction-technique.org/en/tech-writing-process/validation-quality-control/