Qualité

Objectif

Ce document définit les règles de qualité pour la documentation Codexia. Il vise une documentation utile, fiable, accessible, maintenable et simple à auditer.

Inspiration

Ce cadre est inspiré du référentiel Opquast - Qualité Numérique (v5 2025-2030) et du modèle VPTCS (Visibilité, Perception, Technique, Contenus, Services). Les règles ci-dessous sont formulées pour Codexia et ne reprennent pas mot pour mot les libellés Opquast.

Principes directeurs

• Utilité utilisateur : chaque page doit répondre à un besoin clair.
• Vérifiable : une règle doit pouvoir être contrôlée rapidement.
• Universalité : pas de dépendance à un contexte local sauf mention explicite.
• Proportionnalité : le niveau de détail est adapté à l'enjeu.
• Traçabilité : les changements importants sont reportés dans CHANGELOG.md.

Modèle VPTCS appliqué à la documentation

Visibilité

• Toute nouvelle page est référencée dans toc.md ou dans un index de son dossier.
• Les titres sont explicites et cohérents avec le glossaire.
• Les liens entrants depuis README.md et DOCUMENTATION.md sont maintenus à jour si la page est centrale.

Perception

• Une page commence par un résumé court (2 à 5 lignes).
• La hiérarchie de titres est logique et sans saut.
• Les listes et tableaux restent simples et lisibles.
• Le vocabulaire est direct, avec des phrases courtes.

Technique

• Les liens sont relatifs et testables localement.
• Les exemples de commandes ou de configuration sont complets et exécutables.
• Les blocs de code ont un identifiant de langage.
• Les chemins et noms de fichiers sont exacts.

Contenus

• Les affirmations techniques sont précises et datées si nécessaire.
• Les concepts récurrents sont définis dans glossaire.md.
• Les décisions et choix d'architecture sont motivés.
• Les sources externes critiques sont mentionnées.

Services

• Chaque page indique les actions attendues ou les prochaines étapes.
• Les propriétaires ou points de contact sont identifiés quand c'est utile.
• Les impacts de modification sont signalés (risques, compatibilité, migration).

Checklist qualité (a cocher lors d'une revue)

Visibilité

• La page figure dans toc.md ou un index local.
• Le titre est unique et descriptif.
• La page est retrouvable depuis README.md si elle est structurante.

Perception

• Un résumé court est présent en début de page.
• Les titres suivent H1 puis H2/H3 sans saut.
• Les listes restent courtes et non imbriquées.
• Le texte évite le jargon non défini.

Technique

• Tous les liens internes sont valides.
• Les exemples sont reproductibles.
• Les blocs de code ont un langage spécifié.
• Les chemins et noms de fichiers sont exacts.

Contenus

• Les informations sensibles (sécurité, RGPD, credentials) sont traitées correctement.
• Les dates et versions critiques sont explicites.
• Les termes nouveaux sont ajoutés à glossaire.md.
• Les changements notables sont ajoutés dans CHANGELOG.md.

Services

• Les actions ou livrables attendus sont clairs.
• Les impacts de modification sont mentionnés.
• Les dépendances entre pages sont explicites.