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é
Composant concerné : docs/tests/, docs/fr/tests/, mkdocs.yml

1. Contexte et objectif stratégique

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
  2. Lecture des pages docs/tests/*.md et docs/fr/tests/*.md pour identifier les incohérences.

  3. Identification d’une duplication répétitive (“Légende du statut de couverture”) sur chaque page.

  4. Refonte structurelle

  5. Création d’un mécanisme de centralisation (snippet) pour factoriser la légende du statut de couverture.

  6. Harmonisation des titres, des sections et du vocabulaire (dashboard → report / tableau de bord → rapport) uniquement dans les pages de tests.

  7. Navigation améliorée

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

  9. Validation & build

  10. Exécution de mkdocs build pour s’assurer que la documentation se compile sans erreur.
  11. 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.