README de Projet
Un README n'est ni un manuel de paramètres ni une publicité. C'est le chemin le plus court pour aider un nouveau lecteur à faire confiance à un projet et à obtenir un premier résultat.
Ne remplissez pas les sections pour le simple plaisir de les remplir. Un lecteur doit pouvoir répondre à trois questions : Qu'est-ce que c'est ? Est-ce fait pour moi ? Puis-je obtenir un premier résultat et comprendre les limites de risque ?
Principes Fondamentaux
- Chaque affirmation a besoin de preuves. Omettez les affirmations qui ne peuvent pas être vérifiées dans le dépôt ou confirmées par l'utilisateur ; n'adoucissez pas une supposition en prose vague.
- Un guide de démarrage rapide est obligatoire : donnez le chemin réel le plus court de l'installation à un résultat utile. Si ses commandes ne peuvent pas être vérifiées, demandez plutôt que de laisser des blancs ou de les inventer.
- Lorsqu'un README existe déjà, demandez s'il faut le remplacer, conserver du matériel sélectionné, ou l'étendre sur place. Ne devinez pas et n'écrasez pas le contenu écrit par l'utilisateur.
- Établissez l'identité et un point d'entrée au-dessus de la ligne de flottaison. Pour les projets publics, utilisez le nom/logo du projet, une description d'une ligne, de véritables badges et la navigation, puis placez le guide de démarrage rapide immédiatement après. Utilisez un GIF/capture d'écran uniquement lorsqu'il apporte plus que du texte.
- Montrez plutôt que d'affirmer : les sorties terminal, les captures d'écran, le code et les chiffres vérifiés sont plus forts que les adjectifs.
- Organisez par tâche, pas par paramètre. Expliquez « qu'est-ce que je veux faire → quelle commande l'exécute » ; laissez les listes d'options complètes à
--help. - Supprimez toute ligne qui n'aide pas le lecteur à décider, à faire confiance ou à agir.
- Si le projet touche aux fichiers locaux, bases de données, identifiants, réseaux ou appels de modèles, expliquez ce qu'il lit, écrit et envoie hors de l'appareil ainsi que sa posture par défaut (lecture seule/confirmation/sauvegarde/fermeture en cas d'échec). Ne faites aucune promesse de sécurité sans preuve dans le code.
- Gardez le README comme une porte d'entrée ; liez les détails approfondis vers
docs/ouCONTRIBUTING.mdau lieu de transformer le README en manuel. - Adaptez-vous au projet ; n'imposez pas un seul modèle aux CLI, MCP, bibliothèques, applications et dépôts de recherche.
- Évitez les vantardises non vérifiées telles que « leader de l'industrie », « prêt pour la production » ou « performances extrêmes ». Voir les garde-fous dans
content-writing.
Choisir le Public
Classez le lecteur du README pour définir le niveau de détail :
- Solo (projet personnel, outil interne ou script personnel) : le lecteur est principalement vous, incluant votre futur vous. Requis : une description d'une ligne, un guide de démarrage rapide et les limitations connues. Les badges, le guide de contribution, les canaux communautaires, l'historique des étoiles et la feuille de route sont facultatifs. La base est que vous puissiez encore l'exécuter trois mois plus tard.
- Public (open source, logiciel distribué ou partagé en équipe) : le lecteur est un inconnu. Incluez la description, la valeur, le guide de démarrage rapide, l'utilisation, la configuration, l'index de documentation, la contribution et la licence. Ajoutez des badges et des informations communautaires uniquement lorsqu'ils existent réellement.
Par défaut, choisissez Public si le dépôt est public, publié sur un gestionnaire de paquets ou a des utilisateurs externes ; choisissez Solo pour les projets personnels privés et les travaux ponctuels. Pour les cas mixtes, utilisez le niveau de détail Public.
Choisir le Mode
| Mode | Quand l'utiliser | Première étape |
|---|---|---|
| créer | Aucun README n'existe, ou l'utilisateur demande explicitement une réécriture | Inspectez le dépôt et collectez les faits. |
| améliorer | Un README existe et a besoin de travail | Lisez-le, demandez comment gérer le contenu existant, puis procédez. |
| auditer | L'utilisateur demande uniquement un diagnostic | Vérifiez chaque affirmation du README par rapport au dépôt et rapportez les résultats. |
Barrière : Si un README existe, faites une pause pour le choix de l'utilisateur : (1) le remplacer entièrement, (2) le réécrire tout en conservant le matériel spécifié, ou (3) l'étendre sur place. « Aidez-moi à écrire un README » n'implique pas l'option 1.
Au-dessus de la Ligne de Flottaison et Style Outils de Développement (Projets Publics)
Les lecteurs décident de continuer après un écran. Le premier écran doit montrer ce que fait le projet.
Pour les CLI, MCP et outils de développement locaux, privilégiez une documentation de développement sobre et vérifiable :
<div align="center">
Logo optionnel
# Nom du projet
**Description en une ligne**
Uniquement les vrais badges
Sélecteur de langue (uniquement quand l'autre README existe)
Navigation par ancres (lorsque le document dépasse 100 lignes)
</div>
---
Aperçu des capacités : commandes/outils réels, entrées, sorties et posture de sécurité par défaut
Trois règles :
- Description en une ligne : Gardez-la mémorisable et d'environ une ligne : ce que c'est, à qui cela s'adresse et sa distinction factuelle la plus importante. Réservez les principes et le contexte pour plus tard.
- Aperçu des capacités : Listez les commandes/outils réels, les entrées, les sorties, les objets lus/écrits et la posture de sécurité par défaut. Évitez les affirmations génériques comme « rapide, sûr et intelligent ».
- Guide de démarrage rapide ensuite : Privilégiez 1 à 3 étapes les plus courtes. La dernière étape doit vérifier l'installation ou la découverte du service. Placez la configuration complexe plus tard.
Le matériel visuel est facultatif. Choisissez des GIFs/asciinema, des captures d'écran et de véritables sorties terminal uniquement lorsqu'ils apportent des informations. S'il n'y a pas de démo, n'en inventez pas ; donnez plutôt des commandes réelles, la sortie attendue et les étapes de vérification.
Les projets Solo peuvent omettre les logos, badges et la navigation, mais une description d'une ligne et une sortie visible restent utiles.
Échelle de Preuves
Avant d'écrire chaque affirmation, classez sa preuve :
| Niveau | Source | Utilisation |
|---|---|---|
| 1 | Dans le dépôt : source, tests, exemples, configuration, CI, Tags, captures d'écran | Écrivez-la directement. |
| 2 | Confirmée par l'utilisateur : positionnement, différenciation, métriques, captures d'écran, cas | Écrivez-la directement. |
| 3 | Vérifiable en externe : page du paquet, Release, benchmark public | Écrivez-la avec un lien. |
| 4 | Aucune source | Omettez. Demandez si important ; sinon supprimez. |
N'inventez jamais de commandes d'installation, de paramètres CLI, de signatures d'API, de clés de configuration, de variables d'environnement, de chemins, de chiffres de performance, d'affirmations de compatibilité, de termes de licence ou de liens communautaires.
Voir references/evidence.md pour l'analyse du dépôt et les règles de preuve.
Flux de Travail
- Classifiez le public et le mode : solo/public et créer/améliorer/auditer. Si un README existe, demandez comment le gérer avant de le modifier.
- Collectez les preuves du dépôt : inspectez les métadonnées du paquet, les points d'entrée, la structure, la configuration, la documentation, Git/CI, les ressources, les chemins de lecture/écriture, les identifiants, les réseaux, les appels de modèles et les codes d'erreur. Cette étape recueille des faits, pas des conclusions ; voir
references/evidence.md. - Classifiez le projet et le lecteur : CLI, MCP, bibliothèque, application, projet de recherche, compétence d'Agent IA ou monorepo. Utilisez cela pour sélectionner les sections ; voir
references/structure.md. - Vérifiez le guide de démarrage rapide : trouvez et vérifiez la première commande qui produit un résultat utile après l'installation. Si elle ne peut pas être vérifiée, demandez et ne dépassez pas cette barrière.
- Planifiez les sections : sélectionnez les sections pour le type de projet et identifiez les preuves pour chacune. Omettez les sections non prises en charge. Décidez également de la disposition au-dessus de la ligne de flottaison, de la vérification du guide de démarrage rapide, et de la nécessité des sections sur la sécurité/le flux de données, les codes d'erreur ou le dépannage.
- Rédigez un brouillon : identité et capacités → guide de démarrage rapide → fonctionnalités → installation/configuration → utilisation basée sur les tâches → justification/contexte → limites de sécurité/vie privée → erreurs/dépannage → limitations connues → développement/documentation approfondie. Expliquez la justification après que le lecteur a un chemin fonctionnel, pas avant.
- Passez la porte qualité : vérifiez chaque élément dans
references/checklist.md, en particulier l'exactitude factuelle et les étapes exécutables. - Livrez : fournissez un brouillon dans la conversation par défaut ; écrivez sur le disque uniquement sur demande explicite. Ré-exécutez la liste de contrôle avant d'écrire.
Sortie
Énoncez de manière concise : (1) le public et le mode ; (2) le type de projet et le lecteur cible ; (3) le plan des sections et la source de preuve pour chaque section ; (4) le brouillon du README ; (5) les affirmations nécessitant une confirmation de l'utilisateur car les preuves manquent ; et (6) les omissions connues. Ne qualifiez jamais une supposition de vérifiée. Listez explicitement les affirmations non étayées plutôt que de les déguiser avec un langage vague.
Drapeaux Rouges
- Guide de démarrage rapide manquant ou vide, ou commandes inventées sans point d'entrée dans le dépôt.
- Écrasement d'un README existant sans demander comment le gérer.
- Affirmations non confirmées de performance, compatibilité, nombre d'utilisateurs ou nombre d'étoiles.
- Badges pointant vers des CI, paquets ou licences inexistants.
- Remplissage de sections de modèle avec des en-têtes vides ou « TODO/à venir ».
- Intégration d'un manuel d'API complet au lieu de créer un lien vers celui-ci.
- Reproduction d'un long tableau
--helpau lieu d'afficher des commandes basées sur des tâches. - Un écran d'ouverture avec uniquement des slogans ou des principes et aucun point d'entrée réel ou résultat vérifiable.
- Omission des informations de sécurité/flux de données pour les outils qui touchent aux données locales, identifiants, réseaux ou appels de modèles.
- Promesse de fonctionnement en lecture seule, d'absence de fuite de données, de comportement de fermeture en cas d'échec ou de configuration zéro sans preuve dans le code/les tests.
- Dépannage qui dit seulement « redémarrez » sans symptôme, code d'erreur, cause et solution.
- Une description d'une ligne qui est un paragraphe, ou une justification qui apparaît avant le premier chemin exécutable.
- Adjectifs tels que « puissant », « élégant », « extrême » ou « prêt à l'emploi » remplaçant les preuves.
- Forcer des guides de contribution, des codes de conduite ou des liens communautaires sur un projet solo alors qu'ils n'existent pas.
- Diagrammes d'architecture contenant des composants ou des relations d'appel inexistants.
- Écriture de fichiers sans autorisation de l'utilisateur.
Références
Lisez uniquement ce qui est nécessaire :
references/structure.md: flux de lecture, sélection de sections par type de projet, et guide de rédaction de sections.references/evidence.md: analyse du dépôt, niveaux de preuve, et affirmations qui ne doivent pas être inventées.references/checklist.md: porte qualité avant rédaction pour les faits, la convivialité, la présentation et la langue.