Bonnes pratiques de documentation¶

Connaître son audience, maintenir la documentation à jour, et intégrer la doc dans le workflow de développement.

Connaître son audience¶

La documentation n'existe pas dans l'absolu — elle répond aux besoins d'un lecteur spécifique. Avant d'écrire, identifiez qui va lire.

graph LR
    A[Developeur interne] --> B["Reference API\nDocstrings\nADR"]
    C[Nouveau collegue] --> D["Getting started\nGuide d'onboarding\nArchitecture overview"]
    E[Ops / SRE] --> F["Runbook\nDependances\nConfiguration"]
    G[Consommateur externe] --> H["Doc API publique\nChangelog\nGuides d'integration"]

DRY pour la documentation¶

Le principe DRY (Don't Repeat Yourself) s'applique aussi à la doc. Avoir la même information en deux endroits garantit qu'elle sera desynchonisee.

Single source of truth¶

# Mauvais : la version est en trois endroits
README.md                  → "Version : 2.3.0"
docs/installation.md       → "Installer la version 2.3.0"
pyproject.toml             → version = "2.3.0"

# Bon : une seule source, les autres referencent
pyproject.toml             → version = "2.3.0"   (source)
README.md                  → badge dynamique depuis PyPI
docs/                      → genere depuis le code

Inclure plutôt que dupliquer¶

Avec MkDocs, utilisez --8<-- (snippet) pour inclure des extraits d'un fichier dans un autre :

<!-- Dans docs/quickstart.md -->
Voici un exemple complet :

# mkdocs.yml
markdown_extensions:
  - pymdownx.snippets:
      base_path: .

La documentation dans le processus de review¶

Une pull request qui modifie le comportement d'une fonction sans modifier sa docstring est incomplète. Traitez la documentation comme du code.

Checklist de PR documentation¶

## Checklist documentation

- [ ] Les docstrings des fonctions modifiees sont a jour
- [ ] Le CHANGELOG est mis a jour si l'API publique change
- [ ] Un ADR a ete cree si une decision architecturale a ete prise
- [ ] Les exemples dans la doc fonctionnent toujours
- [ ] Le README reflete l'etat actuel si necessaire

Règles de review documentation¶

# .github/CODEOWNERS
docs/          @team-tech-writers @team-leads
docs/decisions/ @team-leads        # ADR reviewes par les leads
openapi.yaml   @team-api

Maintenance de la documentation¶

Détection des docs obsolètes¶

#!/usr/bin/env python3
"""
Detecte les fichiers de documentation non modifies
depuis plus de 180 jours.
"""
import subprocess
from datetime import datetime, timedelta
from pathlib import Path

THRESHOLD_DAYS = 180

def get_last_modified(filepath: str) -> datetime:
    result = subprocess.run(
        ["git", "log", "-1", "--format=%ai", filepath],
        capture_output=True, text=True
    )
    date_str = result.stdout.strip()
    if not date_str:
        return datetime.min
    return datetime.fromisoformat(date_str[:19])

docs_dir = Path("docs")
threshold = datetime.now() - timedelta(days=THRESHOLD_DAYS)

for md_file in docs_dir.rglob("*.md"):
    last_modified = get_last_modified(str(md_file))
    if last_modified < threshold:
        age_days = (datetime.now() - last_modified).days
        print(f"{md_file} — {age_days} jours sans modification")

Tester les exemples de code¶

Les exemples de code dans la documentation doivent être exécutés en CI. Un exemple qui ne fonctionne plus est pire qu'une absence d'exemple.

# docs/examples/quickstart.py — teste en CI
from mon_service import AuthClient

client = AuthClient(
    client_id="test_id",
    client_secret="test_secret",
    base_url="http://localhost:8080"
)
token = client.get_token(scope=["read:users"])
assert token.access_token

# .github/workflows/docs.yml
jobs:
  test-examples:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Test documentation examples
        run: |
          pip install -e ".[dev]"
          python docs/examples/quickstart.py
          python docs/examples/advanced.py

Versionnage de la documentation¶

Quand votre projet a plusieurs versions en production, votre documentation doit aussi être versionnee.

# Avec mike (plugin MkDocs)
pip install mike

# Publier la version 2.1
mike deploy 2.1 latest --push

# Definir la version par defaut
mike set-default latest --push

# Lister les versions
mike list

# mkdocs.yml
plugins:
  - mike:
      version_selector: true
      css_dir: css
      javascript_dir: js

Tableau des pratiques¶

Anti-patterns a éviter¶

Prochaine étape¶

Pour finir ce tutoriel, nous explorons les cas avances : sites de documentation, internationalisation et métriques.

Cas avances →