Écrire un bon README et des ADR

Deux documents, deux rôles

• Le README répond à : « comment démarrer ? »
• Un ADR (Architecture Decision Record) répond à : « pourquoi a-t-on fait ce choix ? »

Le code dit ce que fait le système ; seuls ces documents disent pourquoi.

Un README qui sert

Un lecteur pressé doit pouvoir lancer le projet en moins de cinq minutes.

1. Une phrase de présentation : à quoi sert le projet.
2. Prérequis : versions de Node, outils.
3. Démarrage : les commandes exactes.
4. Commandes courantes : tests, lint, build.
5. Structure : où se trouve quoi.
6. Contribuer : conventions de commit, de branche.

npm install
npm run dev     # http://localhost:3000
npm run check   # à lancer avant de rendre la main

Testez votre README en le suivant sur une machine propre : chaque étape manquante est un bug de documentation.

Les ADR

Un ADR est un court fichier daté qui consigne une décision. Format classique :

# 003 — Pages statiques sans nonce de CSP

## Contexte
Les pages sont prérendues ; un nonce exige un rendu à chaque requête.

## Décision
Nous gardons les pages statiques et autorisons 'unsafe-inline' pour les scripts.

## Conséquences
- Performance maximale.
- Protection XSS moindre, compensée par l'absence de HTML brut.

Bonnes pratiques

• Un ADR par décision, court (une page maximum).
• On n'efface pas un ADR obsolète : on le marque « remplacé par … ».
• Rangez-les dans docs/adr/, numérotés.
• Écrivez-les au moment de la décision, pas six mois après.

Ce que l'on gagne

Un nouvel arrivant comprend les contraintes sans interroger l'équipe, et personne ne remet en cause un choix sans connaître les raisons qui l'ont motivé.

À retenir

Le README aide à démarrer, les ADR aident à comprendre. Les deux se rédigent vite, et s'amortissent à la première personne qui rejoint le projet.