# Validation et contrôle qualité

> **Note**
>
> Un support de rédaction technique doit être soumis à un contrôle qualité rigoureux avant d'être communiqué à ses différentes cibles.
>
> Cet article présente [le workflow de création et validation](#workflow-de-création-et-validation), [les exigences de tout système de suivi](#exigences-de-tout-système-de-suivi), [la comparaison des versions](#comparer-les-versions) et la façon dont [les pull requests et les contrôles automatisés](#pull-requests-et-contrôles-automatisés) reprennent les mêmes principes.

## Définition

Le contenu doit être validé avant livraison. Cela paraît évident, mais cela demande de bien impliquer en amont les personnes chargées de la validation. Idéalement, la phase de validation se déroule en parallèle de la phase de création : plus les modifications interviennent tôt, moins elles sont coûteuses.

> **Schéma: Validation en série ou en parallèle de la rédaction**
>
> Diagramme de Gantt comparant un processus sériel, où la validation ne démarre qu'une fois la rédaction terminée, et un processus parallèle, où la validation démarre dès les premiers modules rédigés, réduisant le délai de publication.

**Valider en parallèle de la rédaction raccourcit le délai de publication.**

## Workflow de création et validation

Un processus de création et de mise à jour de la documentation technique qui repose sur la mémoire des acteurs humains est peu fiable. Un rédacteur technique peut être fatigué, souffrant, en congés, oublier des données lorsqu'il est saturé d'informations ou avoir quitté la société. L'information entre deux personnes peut également mal circuler ou être mal comprise. C'est pour pallier ces faiblesses que l'homme a créé des outils. En revanche, il est créatif, à l'inverse des machines.

> **Schéma: Causes racines d’un processus documentaire peu fiable**

**Un processus basé sur la mémoire humaine est peu fiable.**

Face à cet état de fait, il convient de mettre en place un système de gestion de l'information relative à l'évolution de la documentation qui soit tolérant à l'erreur humaine. Il faut donc soit mettre en œuvre des *workflows* sous un CMS, soit utiliser le système de gestion de tickets du produit documenté.

### Des workflows sous un CMS

Les fonctions principales d’un CMS (Content Management System) sont la gestion des métadonnées, les *workflows* et la traçabilité.

### Le système de gestion de tickets du produit

Le système de gestion de tickets utilisé pour la gestion des nouvelles fonctionnalités du produit documenté (par exemple, Jira) fait suivre à chaque demande de documentation le cycle de vie du ticket :

1. création d'un ticket par un développeur,
2. mise en œuvre du ticket par un rédacteur technique,
3. fermeture du ticket par le créateur du ticket,
4. publication de la documentation lorsque tous les tickets critiques sont fermés.

> **Schéma: Flux de rédaction et de validation documentaire**

**Le workflow de tickets fait progresser chaque demande jusqu'à la publication.**

### Exigences de tout système de suivi

Quel qu'il soit, le système de suivi doit répondre à ces exigences :

- **Traçabilité.** Il doit offrir une visibilité et une traçabilité totales des modifications apportées à la documentation technique (quoi, qui, quand).
- **Un système unique et exhaustif.** Il doit centraliser toutes les demandes de modification de la documentation technique.
- **Un suivi par langue.** Si le document est disponible en plusieurs langues, chaque ticket doit être dupliqué pour chaque langue ou, dans le cas d'un CMS, à chaque langue doit correspondre un *workflow* distinct.

## Compromis

Un outil de gestion de contenu d'entreprise tel qu'Alfresco peut sembler intéressant afin de mettre en place des workflows, sur le papier du moins. Dans les faits, une telle solution peut s'avérer lourde. Elle est de plus peu compatible avec certains formats sources basés sur des documents modulaires et non monolithiques et avec les logiciels de gestion de versions (le projet Componize se propose cependant de gérer des projets DITA XML sous Alfresco).

Il reste cependant impératif de mettre en place des étapes de validation tout au long du projet.

## Comparer les versions

Associés à un système de gestion de versions, les outils de comparaison sont très utiles pour valider les mises à jour. Une version « taguée » d'un projet DITA XML et la version en cours peuvent par exemple être exportées au format RTF, puis comparées sous un traitement de texte. Cela est bien moins fastidieux qu'une relecture comparée. Comparer les modules d'information directement sous le système de gestion de versions n'est pas suffisant, car ils ne sont que les « briques » du document final.

## Pull requests et contrôles automatisés

Lorsque les sources de la documentation sont des fichiers texte dans Git, la pull request assure la traçabilité décrite ci-dessus (quoi, qui, quand, et qui a approuvé), et la comparaison de versions se résume à un `git diff` au lieu d'un export vers un traitement de texte. La validation se répartit alors sur deux niveaux complémentaires :

- les **contrôles automatisés** s'exécutent sur chaque modification avant sa fusion : génération du site, vérification des liens, validation des métadonnées et de la structure. Ils détectent les erreurs mécaniques de façon systématique et peu coûteuse. Voir l'[exemple de pipeline CI/CD](https://docs.redaction-technique.org/fr/toolkit/example-cicd-pipeline/) ;
- la **revue humaine** couvre ce qu'aucun outil ne vérifie : l'exactitude technique par rapport au produit et la qualité rédactionnelle. Voir l'[exemple de workflow de revue](https://docs.redaction-technique.org/fr/toolkit/example-review-workflow/), la [check-list de revue technique](https://docs.redaction-technique.org/fr/toolkit/technical-review-checklist/) et la [check-list de qualité documentaire](https://docs.redaction-technique.org/fr/toolkit/documentation-quality-checklist/).

Un contenu rédigé avec l'aide d'une IA passe par ces deux mêmes niveaux : il ne nécessite pas de processus distinct, mais il nécessite bien la revue humaine.

## Articles connexes

- [Définition du projet](https://docs.redaction-technique.org/fr/tech-writing-process/project-definition/)
- [Collecte de l’information](https://docs.redaction-technique.org/fr/tech-writing-process/gathering-information/)
- [Format source](https://docs.redaction-technique.org/fr/tech-writing-process/source-format/)

---

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