Aller au contenu

Rapport documentaire (docs-report)

Statut

HISTORICAL / TARGET

Le dépôt actuel ne fournit pas de cible make docs-report dans son Makefile.

Cette page conserve donc le rôle conceptuel d’un rapport documentaire, mais ne doit pas être lue comme la preuve qu’une commande docs-report est actuellement disponible.

Rôle

Un rapport documentaire sert à répondre à une question simple :

après validation technique du build, quelles zones de la documentation restent incomplètes, incohérentes ou difficiles à transmettre ?

Il peut couvrir :

  • le volume de pages ;
  • la couverture des sections ;
  • les pages trop courtes ou placeholders ;
  • la présence de statuts CURRENT / TARGET / HISTORICAL ;
  • les zones avec forte dette de transmission ;
  • les anomalies de navigation ou de terminologie.

Ce qui existe aujourd’hui

La validation technique réellement versionnée est :

make docs-check

Le build du site servi est :

make docs-build

Aucune commande docs-report ne doit être inventée entre les deux.

Workflow recommandé en l’absence de commande dédiée

make docs-check
      ↓
revue du lot modifié
      ↓
audit ciblé des pages concernées
      ↓
make docs-build
      ↓
vérification du site servi

Pour un audit documentaire plus large, produire explicitement le rapport comme artefact de revue ou comme page d’audit, sans prétendre qu’il provient d’une commande Runtime inexistante.

Contenu minimal d’un futur rapport automatisé

Si une commande docs-report est réintroduite, elle devrait au minimum distinguer :

  • pages publiées ;
  • pages exclues par exclude_docs ;
  • pages CURRENT ;
  • pages TARGET ;
  • pages HISTORICAL / DEPRECATED ;
  • liens invalides ;
  • pages sans statut lorsqu’un statut est nécessaire ;
  • pages très courtes nécessitant une revue ;
  • sections du mkdocs.yml sans couverture suffisante.

Un simple compteur de fichiers Markdown ne suffit pas à mesurer la qualité de transmission.

Ce qu’un rapport ne prouve pas

Même un rapport automatique complet ne peut pas certifier seul :

  • qu’un fait CURRENT correspond au code actuel ;
  • qu’une commande existe réellement ;
  • qu’une procédure est sûre en production ;
  • qu’un texte est compréhensible pour un nouveau mainteneur ;
  • qu’une page historique n’est pas confondue avec la cible.

Ces points exigent une revue du dépôt et, lorsque nécessaire, du Runtime.

Décision après rapport

Un rapport utile doit conduire à une décision claire :

  • lot prêt à publier ;
  • lot techniquement valide mais transmission incomplète ;
  • informations CURRENT à vérifier ;
  • pages TARGET à reclasser ;
  • publication à bloquer.

Garde-fous

Ne jamais :

  • transformer un score documentaire en certification technique ;
  • masquer les pages faibles parce que le build est vert ;
  • considérer une page volumineuse comme automatiquement complète ;
  • inventer une commande docs-report pour correspondre à ce document.

À retenir

docs-report décrit ici un besoin de gouvernance documentaire, pas une commande CURRENT du dépôt.

La séquence vérifiable aujourd’hui reste : contrôle avec make docs-check, revue humaine, puis build avec make docs-build.

Voir aussi