Skip to content

Test Docs Refactor

Ticket #106: Refactor of test report documentation (FR/EN)
Type: Documentation / Quality improvement
Affected Component: docs/tests/, docs/fr/tests/, mkdocs.yml

1. Context and strategic objective

Automated test documentation is a key asset for tracking and trusting test coverage. This work aimed to make that documentation:

  • more consistent between the French and English versions,
  • easier to maintain (by reducing redundant content),
  • more accessible through clear navigation (menu links) and unified terminology (report/rapport).

2. Approach & process

  1. Current-state analysis

    • Reviewed docs/tests/*.md and docs/fr/tests/*.md pages to identify inconsistencies.
    • Spotted repeated duplication of the “Coverage status legend” on every page.

  2. Structural refactor

    • Tried to create a central reusable snippet for the coverage status legend.
    • Harmonized titles, sections and vocabulary (dashboard → report / tableau de bord → rapport) only within test documentation pages.

  3. Improved navigation

    • Updated the MkDocs menu so test report pages are directly accessible via the left-hand navigation.

  4. Validation & build

    • Ran mkdocs build to ensure the docs compile without errors.
    • Used mkdocs serve for a visual check of the rendered output.

3. Challenges encountered

  • Markdown inclusion handling: the initial attempt to factor the legend via {% include ... %} did not render correctly (the directive appeared literally). I reverted to a simpler approach to guarantee consistent rendering.
  • FR/EN synchronization: some pages had diverged due to manual edits, requiring careful review to keep intent aligned and avoid drift.
  • “dashboard” vs “report” terminology: the term “dashboard” was also used for the application feature. The challenge was to apply the terminology change only within test documentation, without altering application semantics.

4. Results achieved

  • Clear navigation between all test report pages (via the MkDocs sidebar).
  • Consistent terminology in the test-docs space (report / rapport), without touching other project areas.
  • More maintainable documentation with reusable elements and a uniform structure.
  • A successful MkDocs build, with no compilation errors related to the docs.

5. Next steps (suggested)

  • Add an automated pytest that validates each test page contains the expected coverage-status block.
  • Create an overview page for activity reports (separate ticket) to present the intervention log centrally.
  • Optionally add an automatic generation mechanism for the list of test pages to reduce manual menu maintenance.