README Engineering & Technical Documentation Guide

Guide d'ingénierie des README et de la documentation technique

Un cadre rigoureux pour créer des READMEs de dépôts GitHub de qualité humaine, respectueux du temps du lecteur, communiquant clairement la valeur technique et éliminant le remplissage marketing générique.

---

1. La philosophie centrale : la règle des 30 secondes

Les développeurs et les utilisateurs ne « lisent » pas la documentation du début à la fin — ils la scannent à grande vitesse. Mettez-vous à la place d'un développeur fatigué qui vient de tomber sur votre dépôt à 2 heures du matin.

Votre README doit répondre à trois questions en moins de 30 secondes :

1. Qu'est-ce que c'est ? (Une définition claire en une seule phrase, sans aucun marketing).
2. Pourquoi devrais-je m'y intéresser ? (Le problème réel qu'il résout et les solutions de contournement frustrantes qu'il remplace).
3. Comment l'exécuter maintenant ? (Un démarrage rapide en 3 étapes, copiable, avec des commandes testées).

---

2. Directives pour une écriture claire et fondée

La documentation tombe souvent dans un discours d'entreprise gonflé. Les projets open source de haute qualité évitent complètement ce ton.

2.1 Le dictionnaire des mots et clichés interdits

❌ Mot à la mode / Cliché interdit	✔️ Alternative claire et fondée
« Dans le paysage numérique actuel en évolution rapide... »	(Supprimer complètement. Aller directement au problème).
« Transférez sans effort / intégrez de manière transparente... »	« Déposez des fichiers depuis votre navigateur et ils apparaissent sur votre téléphone. »
« Une plateforme révolutionnaire et de pointe... »	« Un relais personnel léger et auto-hébergé. »
« Élève votre productivité à de nouveaux sommets... »	« Vous évite de vous envoyer des liens par e-mail. »
« Un témoignage du développement moderne... »	(Supprimer. Parlez comme un ingénieur, pas comme une agence de relations publiques).
« Bannières géantes complètement éliminées... »	(Ne vous vantez jamais de refontes internes. Indiquez ce que l'interface utilisateur offre maintenant).
« Architecture d'authentification web défensive... »	« Connexion sécurisée utilisant des cookies HttpOnly SameSite et des jetons CSRF. »
« Cache SWR zéro squelette... »	« Chargement instantané : ouvre votre boîte de réception sans écran blanc vide. »

2.2 Règles pour une écriture authentique

• Le test du « café du mardi » : Lisez votre brouillon à voix haute. Cela ressemble-t-il à un ingénieur logiciel réfléchi expliquant son outil préféré à un collègue autour d'un café ? Si cela ressemble à une brochure marketing d'entreprise, réécrivez-le.
• Discipline des badges : Limitez les badges à 3 à 6 indicateurs significatifs (Version, État de la build/CI, Licence, Stack principale). N'empilez pas 15 badges décoratifs qui distraient du projet.
• Pas de prérequis mystères : N'écrivez jamais docker compose up ou npm start sans lister les prérequis et l'origine des identifiants d'environnement.

---

3. La structure à double audience

Une bonne documentation fait le pont entre deux publics distincts sans compromettre la clarté :

flowchart TD
    Audience["Visiteur du dépôt"]
    Audience --> HomeUser["1. Personne normale / Utilisateur quotidien<br>(Veut savoir si cela résout son problème)"]
    Audience --> Sysadmin["2. Ingénieur / Administrateur système / Développeur<br>(Veut connaître l'architecture, la sécurité et la pile)"]

    HomeUser --> PlainSection["Section « Pourquoi cela existe ? »<br>- Situations réelles (plus d'envoi de SMS ou de pièces jointes)<br>- Flux de travail conceptuel en 3 étapes<br>- Avantages en matière de confidentialité et d'auto-hébergement"]
    Sysadmin --> TechSection["Section « Comment ça marche »<br>- Diagramme d'architecture (Mermaid)<br>- Responsabilités des composants<br>- Modèle de sécurité et de jetons<br>- Mécanismes de stockage et de base de données"]

3.1 Langage simple pour les utilisateurs quotidiens

Commencez par un problème du monde réel auquel on peut s'identifier :

« Vous est-il déjà arrivé de vous envoyer un lien par e-mail, de messager à un bot sur Telegram ou WhatsApp juste pour copier du texte sur votre téléphone, ou d'attendre la synchronisation d'un cloud pour déplacer un seul PDF ? Vault remplace ces solutions de contournement par votre propre boîte de dépôt privée. »

3.2 Profondeur technique fondée pour les développeurs

Enchaînez avec une architecture précise et des détails d'implémentation :

• Moteur API : ASP.NET Core 10 Minimal APIs streamant des fichiers jusqu'à 100 Mo directement sur disque avec vérification SHA-256 à la volée (zéro gonflement RAM).
• SPA Web : React 19 + TypeScript avec cookies HttpOnly SameSite, jetons CSRF et raccourcis clavier (recherche /).
• Client mobile : Kotlin Jetpack Compose natif avec files d'attente de messages hors ligne WorkManager et intégration Android FileProvider.
• Base de données : PostgreSQL 18 stockant les métadonnées et les jetons de session glissants de 14 jours.

---

4. Vitrines visuelles et mises en page de l'interface utilisateur

Si votre application a une interface visuelle (Web, Mobile ou sortie CLI), montrez-la immédiatement après le pitch d'introduction.

4.1 Modèle de tableau de vitrine réactif

<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 Boîte de réception mobile</th>
<th width="33%" align="center">⚙️ Hub des appareils</th>
<th width="34%" align="center">🔐 Appairage transparent</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="Boîte de réception mobile" width="260px" />
<br/>
<sub><i>Cache local instantané, recherche en direct et actions en un clic.</i></sub>
</td>
<!-- Colonnes restantes -->
</tr>
</table>

4.2 Règles pour les captures d'écran :

• Légendes informatives : Utilisez des légendes pour décrire ce que l'utilisateur peut faire dans la vue, pas pour enchaîner des mots à la mode.
• Captures d'écran réelles : Utilisez toujours des captures nettes de l'interface utilisateur réelle du produit plutôt que des maquettes génériques avec de faux cadres d'ordinateur portable.

---

5. Conception de démarrage rapide sans faille

Les démarrages rapides doivent être reproductibles sans dépannage.

Le processus standard en 3 étapes :

### 1. Générer les certificats et identifiants locaux
```bash
./scripts/setup-local.sh  # or ./scripts/setup-local.ps1

Ce que cela fait : Génère un certificat TLS localhost de confiance dans .local/tls/ et écrit un mot de passe d'amorçage aléatoire dans .env.

2. Démarrer la pile

docker compose up -d

3. Ouvrir votre espace de travail

Accédez à https://localhost:8080 dans votre navigateur :

• Nom d'utilisateur : [email protected] (ou owner)
• Mot de passe : Le mot de passe d'amorçage dans votre fichier .env

---

## 6. Liste de contrôle de la structure standard du README

Utilisez cette liste de contrôle lors de la structuration de tout README de dépôt technique :

- [ ] **1. En-tête et titre :** Logo / Icône, titre et slogan fonctionnel en une phrase.
- [ ] **2. Badges ciblés :** Version de la version, État de la build, Plateformes principales, Licence.
- [ ] **3. Pourquoi cela existe :** Le problème quotidien, la solution et le flux de travail en 3 étapes en langage simple.
- [ ] **4. Visite visuelle :** Captures d'écran des interfaces Web, Mobile ou CLI avec des légendes pratiques.
- [ ] **5. Capacités principales :** Liste de fonctionnalités centrées sur l'utilisateur, organisées par tâches réelles.
- [ ] **6. Comment ça marche (technique) :** Diagramme d'architecture Mermaid + répartition concise des composants (API, Client, DB, Auth/Sécurité).
- [ ] **7. Démarrage rapide (Docker / Local) :** Prérequis, commandes étape par étape et emplacements des identifiants.
- [ ] **8. Configuration mobile / client (si applicable) :** Liens de téléchargement directs, instructions d'appairage et guide de test LAN.
- [ ] **9. Tests automatisés et vérification :** Commandes pour exécuter les suites de tests backend et frontend localement.
- [ ] **10. Carte du dépôt et contribution :** Arborescence ASCII propre des dossiers, lien vers les directives et licence MIT/Apache.

---

## 7. Dépôts open source de référence

Inspectez ces READMEs open source réputés pour vous inspirer sur le plan structurel et visuel :

- **`matiassingers/awesome-readme`** : Répertoire organisé des meilleurs READMEs sur GitHub.
- **`othneildrew/Best-README-Template`** : La référence absolue du secteur pour les modèles de dépôts modulaires et à fort impact.
- **`charmbracelet/bubbletea` & `charmbracelet/gum`** : Vitrines terminales exceptionnelles, utilisation de GIF et blocs de code scannables.
- **`supabase/supabase`** : Excellent équilibre entre les deux publics avec des diagrammes d'architecture système clairs et une intégration rapide.
- **`fastapi/fastapi`** : Cours magistral sur les démarrages rapides sans friction, les exemples de code réels et la proposition de valeur claire.