README qui vend

Que fait README qui vend ?

Un README n'est pas de la documentation. C'est une page d'atterrissage qui se trouve dans un dépôt git. Un visiteur décide en environ 15 secondes s'il va mettre une étoile, essayer ou partir. Tout ce qui se trouve au-dessus de la ligne de flottaison doit gagner l'étoile. La documentation se place en dessous de la ligne de flottaison ou dans docs/.

Le test des 15 secondes

Avant d'écrire quoi que ce soit, répondez à ces questions en une ligne chacune. Si vous ne le pouvez pas, le README non plus.

1. Qu'est-ce que c'est ? Une phrase, sans adjectifs. « Un navigateur headless pour agents IA, écrit en Zig. »
2. Pourquoi ça existe ? La douleur qu'il élimine, dans les mots de l'utilisateur. « Chrome mange 500 Mo par onglet ; les agents ont besoin de 50 onglets. »
3. Preuve que ça fonctionne. Un GIF de démonstration, un chiffre de benchmark, ou un avant/après. Pas une liste de fonctionnalités.
4. Comment l'essayer en une commande ? npx ..., pip install ..., curl ... | sh, docker run ....

Structure (dans cet ordre, sans exception)

# nom-du-projet
Phrase d'accroche en une phrase. (quoi + pour qui + l'accroche)

[GIF de démo ou capture d'écran — moins de 10 secondes, montre le résultat, pas l'installation]

## Installation           ← une commande, copiable, pas de prérequis cachés
## Pourquoi               ← 3–5 lignes : la douleur, les alternatives existantes, pourquoi ce projet est différent
## Utilisation             ← le cas le plus courant, sous forme d'exemple exécutable
## Fonctionnalités          ← optionnel, court, liste à puces, pas d'adjectifs marketing
## Comment ça marche      ← optionnel, un paragraphe ou un diagramme
## Comparaison        ← tableau optionnel vs 2–3 alternatives, honnête sur les compromis
## Contribution / Licence

Règles

• Ligne d'accroche : ≤ 15 mots. Nommez la catégorie et le différenciateur. Évitez « ultra rapide », « puissant », « simple mais ». Si ça contient un chiffre, utilisez le chiffre : « Réduit de 40 % la consommation de tokens de Claude Code. »
• Démo d'abord, mots ensuite. Le GIF ou la capture d'écran se place immédiatement sous l'accroche. S'il n'y a pas encore de démo, créez-en une avant le lancement (voir le skill demo-gif). Un README sans démo convertit à une fraction de celui qui en a une.
• L'installation est un bloc, une commande. Si ça nécessite une clé API ou un fichier de configuration, montrez-le aussi, dans le même bloc. Les prérequis cachés sont la première raison pour laquelle les gens partent après avoir cloné.
• Le « Pourquoi » est écrit pour quelqu'un qui a déjà une solution. Nommez les alternatives. Dites ce qu'elles font bien. Puis dites la seule chose que ce projet fait qu'elles ne font pas. Les lecteurs font confiance aux README qui sont justes envers les concurrents.
• Pas d'émojis dans les titres sauf si le projet est délibérément ludique. Pas de badges au-dessus de l'accroche (un mur de badges est la première chose que les visiteurs font défiler). Deux ou trois badges sous l'accroche c'est bien : statut de build, version, licence.
• Un exemple concret vaut mieux que dix puces de fonctionnalités. Montrez entrée → sortie. Faites en sorte que le lecteur puisse réellement l'exécuter.
• Dites ce que ce n'est pas. Une ligne de périmètre honnête (« Pas un remplacement de Playwright ; pas de rendu JS pour l'instant ») prévient le premier commentaire hostile sur Hacker News.
• Liez la preuve sociale que vous avez. « Utilisé par X », un benchmark, un fil Show HN. N'en inventez aucune.
• Gardez les 60 premières lignes libres de tout ce dont un visiteur novice n'a pas besoin. Architecture, feuille de route, FAQ, journal des modifications : tout en dessous ou ailleurs.

Anti-patrons qui tuent la conversion

• Commencer par un paragraphe de contexte ou d'histoire.
• Une table des matières comme première chose sur la page.
• Les « Fonctionnalités » avant « Installation ».
• Des instructions d'installation qui commencent par « D'abord, clonez le dépôt » pour un outil destiné à être utilisé, pas développé.
• Des captures d'écran de fichiers de configuration au lieu des résultats.
• Un ton marketing (« révolutionnaire », « nouvelle génération », « sans effort »).
• Des placeholders morts (« TODO : ajouter une démo »).

Procédure

1. Lisez le README actuel (s'il y en a un) et les points d'entrée du code. Extrayez les quatre réponses du test des 15 secondes.
2. Rédigez la ligne d'accroche. Écrivez trois variantes ; choisissez celle qui a le nom le plus concret et le moins d'adjectifs.
3. Écrivez Installation, puis Utilisation, puis Pourquoi. Exécutez chaque commande d'installation pour confirmer qu'elle fonctionne depuis un répertoire propre.
4. Insérez la démo sous l'accroche. Si elle n'existe pas, ajoutez un marqueur TODO(demo) et dites à l'utilisateur que cela bloque le lancement.
5. Supprimez tout ce qui se trouve au-dessus de la ligne de flottaison et qui ne répond pas à la question « un inconnu a-t-il besoin de cela pour décider ? »
6. Lisez les 60 premières lignes en tant qu'ingénieur sceptique. Corrigez la première chose qui les ferait fermer l'onglet.

Résultat

Retournez le README.md complet. Ensuite, listez, en ≤ 5 puces, ce que vous avez changé et ce que l'utilisateur doit encore fournir (GIF de démo, chiffres de benchmark, citations d'utilisateurs réels).