Fondamentaux de la documentation¶

Documentation as code, pyramide de documentation et les quatre questions essentielles pour rendre votre code comprehensible.

Pourquoi documenter ?¶

Le code que vous ecrivez aujourd'hui sera lu bien plus souvent qu'il ne sera écrit. Par vous dans six mois, par un collegue demain, par un futur mainteneur que vous ne connaissez pas encore.

La documentation ne sert pas a expliquer ce que le code fait — le code lui-même doit être lisible. Elle sert à expliquer pourquoi une décision a été prise, quel problème elle résout, et comment s'y intégrer.

Principe fondateur

"Code tells you how, comments tell you why." — Jeff Atwood

La pyramide de documentation¶

graph TD
    A["README / Getting Started"] --> B["Guides et tutoriels"]
    B --> C["Reference technique"]
    C --> D["Architecture Decision Records"]
    D --> E["Commentaires inline"]
    style A fill:#e8f5e9
    style B fill:#c8e6c9
    style C fill:#a5d6a7
    style D fill:#81c784
    style E fill:#66bb6a

Chaque niveau répond a un besoin différent :

Niveau	Audience	Question repondue	Localisation
README	Tout le monde	Qu'est-ce que c'est ?	Racine du dépôt
Guides	Nouveaux devs	Comment démarrer ?	`docs/guides/`
Référence technique	Devs qui codent	Quelle API utiliser ?	Côté du code
ADR	Équipe / futurs	Pourquoi ce choix ?	`docs/decisions/`
Commentaires inline	Le dev qui lit	Pourquoi ce code ?	Dans le fichier source

Les quatre questions de la documentation¶

Avant d'écrire quoi que ce soit, posez-vous ces quatre questions :

1. Qui lit cette documentation ?¶

Un développeur qui intégré votre librairie ?
Un ops qui deploie votre service ?
Un nouveau membre de l'équipe ?
Vous-même dans six mois ?

2. Que veut-il savoir ?¶

Comment démarrer rapidement (onboarding) ?
Le détail d'une fonction particulière (référence) ?
Pourquoi l'architecture est telle qu'elle est (ADR) ?
Comment résoudre un problème spécifique (guide) ?

3. Pourquoi en a-t-il besoin maintenant ?¶

Le contexte détermine le format. Un développeur qui debogue a besoin de la référence technique. Un nouveau collaborateur a besoin d'un guide pas a pas.

4. Comment trouver l'information ?¶

La meilleure documentation est inutile si elle est introuvable. Pensez à la navigation, aux liens croisés, à l'indexation.

Documentation as code¶

L'approche "documentation as code" signifie appliquer au contenu documentaire les mêmes pratiques qu'au code source :

Versionne dans Git, avec le code qu'il documente
Revu en pull request comme n'importe quel changement
Teste (liens valides, exemples qui compilent)
Généré automatiquement quand c'est possible
Publie via un pipeline CI/CD

sequenceDiagram
    participant Dev as Developpeur
    participant PR as Pull Request
    participant CI as Pipeline CI
    participant Site as Site de doc

    Dev->>PR: Modifie code + doc ensemble
    PR->>CI: Declenche validation
    CI->>CI: Verifie liens, lint markdown
    CI->>Site: Deploie si merge
    Site-->>Dev: Documentation a jour

Avantages concrets¶

Pratique	Avantage
Doc dans le même repo	Jamais desynchronisee du code
Review obligatoire	La doc est relue et améliorée
CI sur la doc	Les liens morts sont détectés automatiquement
Historique Git	On sait quand et pourquoi la doc a change

Documentation proche du code vs documentation externe¶

Documentation proche du code¶

Docstrings et commentaires inline
Fichiers README dans chaque sous-dossier
Exemples de tests (les tests documentent le comportement attendu)

# docs/modules/auth/README.md explique l'intention generale
# auth/token.py contient les docstrings de chaque fonction
# tests/test_token.py montre comment utiliser les fonctions

Documentation externe¶

Guides d'installation et de démarrage
Tutoriels pas a pas
Documentation d'API générée (Swagger, Redoc)
ADR (décisions d'architecture)

Règle pratique

Si la documentation change quand le code change — mettez-la dans le même fichier ou le même dossier. Si elle reste stable independamment du code, mettez-la dans docs/.

Quand documenter ?¶

Documenter avant de coder (docs-driven development)¶

Écrire la docstring ou le README d'une fonction avant de l'implémenter force a clarifier ce qu'elle doit faire. C'est une forme de spécification.

def calculate_discount(price: float, user_tier: str) -> float:
    """
    Calcule la remise applicable a un utilisateur selon son niveau.

    Les regles metier sont definies dans la spec produit v2.3 :
    - tier "standard" : 0%
    - tier "premium"  : 10%
    - tier "vip"      : 20%

    Args:
        price: Prix original en euros, doit etre positif.
        user_tier: Niveau de l'utilisateur ("standard", "premium", "vip").

    Returns:
        Prix apres remise.

    Raises:
        ValueError: Si user_tier n'est pas un niveau connu.
    """
    # Implementation a venir
    pass

Documenter pendant le code¶

Annotez les décisions non-évidentes au moment où vous les prenez — c'est quand le contexte est le plus frais.

Documenter après le code¶

Pour les guides et tutoriels, attendre que l'API se stabilise evite de reecrire la doc à chaque refactoring.

Piege classique

"Je documenterai plus tard." Plus tard arrive rarement. Reservez la documentation post-code aux guides de haut niveau, pas aux docstrings qui doivent accompagner chaque fonction.

Le README comme porte d'entree¶

Un bon README répond en moins de deux minutes a ces questions :

Qu'est-ce que c'est ? (une phrase)
A qui ca sert ? (le cas d'usage principal)
Comment installer ? (commandes copiables)
Comment l'utiliser ? (exemple minimal fonctionnel)
Comment contribuer ? (lien vers CONTRIBUTING.md)

# mon-service

Service d'authentification OAuth2 pour les applications internes.

## Installation

pip install mon-service

## Demarrage rapide

from mon_service import AuthClient

client = AuthClient(client_id="...", client_secret="...")
token = client.get_token(scope=["read:users"])

Prochaine étape¶

Dans le chapitre suivant, vous apprendrez a écrire des docstrings efficaces dans les principaux langages et à les transformer en documentation générée automatiquement.

Docstrings et commentaires →