Fondamentaux de la documentation technique¶

Pourquoi centraliser la documentation¶

La documentation technique d'une DSI est souvent dispersee entre des wikis internes, des fichiers Confluence, des README Git, des partages réseau et des emails. Cette dispersion a un coût concret : retrouver une procedure, vérifier la date de mise à jour d'un document ou auditer les accès devient une tâche manuelle et peu fiable.

Centraliser la documentation dans un service dedie répond a quatre besoins fondamentaux :

1. Découverte — un seul point d'entree, une navigation coherente, un moteur de recherche commun
2. Cohérence — templates uniformes, conventions de nommage communes, style homogène
3. Gouvernance — qui a écrit quoi, qui peut modifier, circuit de validation
4. Auditabilite — historique complet des modifications, attributable a un auteur, réversible

Documentation-as-Code¶

Principe¶

Documentation-as-Code est l'application aux documents techniques des mêmes pratiques que pour le code source : les fichiers sont écrits en texte brut (Markdown), stockes dans Git, et publies automatiquement via un pipeline CI.

graph LR
    MD["Markdown<br/>(fichiers .md)"] -->|git push| Git["Depot Git<br/>(Gitea / GitHub)"]
    Git -->|webhook| CI["Pipeline CI<br/>(Forgejo Actions)"]
    CI -->|mkdocs build| SSG["Site statique<br/>(HTML/CSS/JS)"]
    SSG -->|deploiement| RP["Reverse proxy<br/>(Caddy / Nginx)"]
    RP -->|HTTPS| Lecteur["Lecteur"]

Le flux complet — de la modification d'un fichier Markdown jusqu'a la page visible par le lecteur — est automatise. L'auteur n'a pas a se connecter a une interface d'administration : un simple git push suffit.

Avantages par rapport à un wiki WYSIWYG¶

Un wiki WYSIWYG (Confluence, Notion, MediaWiki) offre une prise en main rapide mais accumule des limitations à l'échelle :

Types de documentation — modèle Diataxis¶

Les quatre types¶

Le modèle Diataxis (Daniele Procida, 2017) distingue quatre types de documentation selon deux axes : apprentissage vs travail et théorique vs pratique.

Quadrant Diataxis¶

quadrantChart
    title Modele Diataxis
    x-axis Theorique --> Pratique
    y-axis Travail --> Apprentissage
    quadrant-1 Tutoriels
    quadrant-2 Explication
    quadrant-3 Reference
    quadrant-4 Guides pratiques
    Tutoriels: [0.75, 0.75]
    Guides pratiques: [0.75, 0.25]
    Reference: [0.25, 0.25]
    Explication: [0.25, 0.75]

Generateurs de sites statiques (SSG)¶

Principe de fonctionnement¶

Un generateur de site statique (SSG) compile des fichiers sources — Markdown, YAML, templates — en un ensemble de fichiers HTML, CSS et JavaScript prets a etre servis par n'importe quel serveur web.

Contrairement a une application web dynamique :

• Aucune base de données a maintenir ou securiser
• Aucun runtime serveur (PHP, Node, Python) expose en production
• Les fichiers générées sont deployables sur un simple serveur HTTP, un CDN ou un bucket objet (S3, MinIO)
• Performance maximale : chaque page est un fichier statique servi directement par le serveur
• Surface d'attaque reduite : pas d'injection SQL, pas d'execution de code serveur côté visiteur

Comparaison des SSG populaires¶

MkDocs et MkDocs Material¶

MkDocs¶

MkDocs est écrit en Python. Il parcourt l'arborescence de fichiers Markdown, applique des templates Jinja2 et produit un site HTML statique. La configuration est entierement declarative dans un fichier YAML.

Structure de projet type :

mon-projet-docs/
├── mkdocs.yml          # Configuration principale
├── docs/               # Sources Markdown
│   ├── index.md
│   ├── guide/
│   │   └── installation.md
│   └── reference/
│       └── api.md
└── site/               # Sortie generee (ne pas versionner)

Le fichier mkdocs.yml contrôle la navigation, le theme, les plugins et les extensions Markdown :

site_name: Documentation interne
docs_dir: docs
site_dir: site

nav:
  - Accueil: index.md
  - Guide:
    - Installation: guide/installation.md
  - Reference:
    - API: reference/api.md

theme:
  name: material

plugins:
  - search

markdown_extensions:
  - admonition
  - pymdownx.superfences

Les commandes essentielles sont :

• mkdocs serve — serveur de développement avec rechargement automatique
• mkdocs build — génération du site statique dans site/
• mkdocs gh-deploy — déploiement vers GitHub Pages (optionnel)

MkDocs Material¶

MkDocs Material est une surcouche de theme appliquant le langage de design Material Design de Google. Il est maintenu par Martin Donath (squidfunk) et est l'un des projets Python les plus stars sur GitHub.

Fonctionnalités cles :

• Navigation par onglets et sections : organisation hierarchique de la documentation avec onglets de premier niveau et sections pliables dans le menu lateral
• Recherche client-side (Lunr) : index de recherche génère a la compilation, interroge directement dans le navigateur sans serveur, avec mise en évidence des termes
• Coloration syntaxique : integre via Pygments ou highlight.js, supporte des dizaines de langages avec themes clairs et sombres
• Admonitions : blocs visuels differencies (note, tip, warning, danger, info, example, quote) pour attirer l'attention du lecteur
• Diagrammes Mermaid : rendu natif des diagrammes Mermaid via le plugin superfences
• Responsive : adaptatif mobile/tablette/desktop sans configuration supplémentaire

Extensions Markdown utiles¶

Les extensions PyMdown etendent la syntaxe Markdown standard avec des fonctionnalités orientees documentation technique :

Exemple de configuration complète des extensions dans mkdocs.yml :

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true

Vocabulaire cle¶

Synthese¶

La documentation technique centralisee repose sur un principe simple : traiter les documents comme du code. Markdown dans Git, pipeline CI, site statique — cette chaîne garantit la traçabilite, la réversibilité et l'automatisation de la publication. MkDocs Material est la solution de référence pour une DSI qui veut un résultat professionnel sans complexité operationnelle. Le modèle Diataxis fournit le cadre conceptuel pour structurer le contenu de manière coherente et utile. Le chapitre suivant presente les solutions disponibles et leurs critères de choix.