Aller au contenu

Refonte Docs Tests

Billet #106 : Refactoring de la documentation des rapports de test (FR/EN)
Type : Documentation / Amélioration de la qualité
Composants concernés : docs/tests/, docs/fr/tests/, mkdocs.yml

1. Contexte et objectif

La documentation des tests automatisés est un élément clé pour assurer la traçabilité et la confiance dans la couverture des tests. Cette activité visait à rendre cette documentation :

  • plus cohérente entre les versions française et anglaise,
  • plus facile à maintenir (en évitant les duplications inutiles),
  • plus accessible via une navigation claire (liens de menu) et une terminologie unifiée (report/rapport).

2. Approche & démarche

  1. Analyse de l’existant

    • Lecture des pages docs/tests/*.md et docs/fr/tests/*.md pour identifier les incohérences.
    • Identification d’une duplication répétitive (“Légende du statut de couverture”) sur chaque page.

  2. Refonte structurelle

    • Création d’un mécanisme de centralisation (snippet) pour factoriser la légende du statut de couverture.
    • Harmonisation des titres, des sections et du vocabulaire (dashboard → report / tableau de bord → rapport) uniquement dans les pages de tests.

  3. Navigation améliorée

    • Mise à jour du menu MkDocs pour exposer une navigation directe entre les pages de tests via la barre de gauche, améliorant l’expérience de lecture.

  4. Validation & build

    • Exécution de mkdocs build pour s’assurer que la documentation se compile sans erreur.
    • Vérification visuelle (via mkdocs serve) pour confirmer la qualité de rendu.

3. Défis rencontrés

  • Gestion des inclusions Markdown : la tentative initiale de factorisation via {% include ... %} n’a pas fonctionné correctement (le rendu affichait littéralement la directive). Il a fallu revenir à une approche plus simple pour garantir un rendu stable.
  • Synchronisation FR/EN : certains éléments avaient été modifiés manuellement entre les versions, ce qui a nécessité une relecture attentive pour conserver l’intention et éviter les divergences.
  • Terminologie “dashboard” vs “report” : l’usage du terme “dashboard” existait également pour la fonctionnalité applicative. L’enjeu a été de ne modifier la terminologie que dans les documents de tests, sans impacter la fonctionnalité elle-même.

4. Résultats obtenus

  • Une navigation claire entre toutes les pages de rapport de test (via le menu MkDocs).
  • Une terminologie cohérente dans l’espace “test docs” (report / rapport), sans toucher au reste du projet.
  • Une documentation plus maintenable, avec des éléments réutilisables et une structure homogène.
  • Un build MkDocs fonctionnel, sans erreur de compilation liée à la documentation.

5. Prochaines étapes (suggérées)

  • Mettre en place un test automatisé (pytest) qui vérifie que chaque page de test contient bien le bloc de statut de couverture attendu.
  • Créer une page d’aperçu (overview) pour les rapports d’activité (ticket séparé), afin de présenter le journal des interventions de manière centralisée.
  • Éventuellement ajouter un mécanisme de génération automatique de la table de liens vers les pages de tests afin de réduire le besoin de maintenances manuelles.