Rédacteur de README
Un README n'a qu'une seule mission : faire passer un visiteur de « qu'est-ce que c'est ? » à une première commande fonctionnelle en moins d'une minute, puis lui montrer comment aller plus loin et comment aider.
Quand l'utiliser
- Écrire un README pour un nouveau projet, ou réécrire un README trop succinct ou décousu
- Relire un README avant un lancement ou une version 1.0
- L'utilisateur dit que le projet reçoit des visites mais pas d'étoiles, d'installations ou de contributeurs
Quand ne pas l'utiliser
- Documentation de référence d'API (générez-la depuis le code ; liez-la depuis le README)
- Longs tutoriels ou documentation d'architecture : placez-les dans
docs/et créez des liens
Workflow
-
Recueillir les faits avant d'écrire. Lisez le manifeste (
pyproject.toml,package.json,composer.json,Cargo.toml...), l'aide--helpde la CLI ou le point d'entrée principal, la documentation existante et la licence. Trouvez la véritable commande d'installation et un exemple concret. N'inventez jamais de drapeaux, de sorties, de benchmarks ou de fonctionnalités. -
Ne demander à l'utilisateur que ce que le code ne peut pas révéler : à qui s'adresse le projet, le seul problème qu'il résout, et pourquoi il est meilleur que l'alternative évidente. Si l'utilisateur n'est pas disponible, rédigez une accroche neutre à partir du code et marquez-la pour révision.
-
Linter le README actuel (s'il existe).
scripts/est relatif à ce skill :python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
Écrire en suivant la structure de structure.md, en partant du modèle. L'ordre compte : titre + badges, accroche, (image de démo), démarrage rapide, fonctionnalités, utilisation/exemples, configuration, FAQ, feuille de route, contribution, licence.
-
Appliquer les règles d'écriture :
- Accroche : une phrase, moins de 200 caractères, pas de mots pompeux. Modèle :
«
<nom>est un<catégorie>qui<fait X>pour<public>,<différenciateur clé>. » - Premier bloc de code avant la ligne 60. Chaque commande doit être copiable et réelle.
- Afficher la sortie après les commandes lorsque cela aide (
# => ...ou un bloc séparé). - Utiliser des tableaux pour les options et comparaisons, des listes pour les fonctionnalités (avantage en premier).
- Créer des liens, ne pas coller : les documentations longues, les journaux de modifications et les références d'API vont ailleurs.
- Chaque image doit avoir un texte alternatif ; préférer un SVG ou un court GIF du flux principal.
- Accroche : une phrase, moins de 200 caractères, pas de mots pompeux. Modèle :
«
-
Badges. N'utilisez que des badges vrais et maintenus, dans cet ordre : état CI, dernière version (PyPI/npm/Packagist/release), téléchargements (optionnel), licence. Exemples dans structure.md.
-
Relinter jusqu'à ce qu'il n'y ait plus d'erreurs. Résolvez les avertissements ou dites à l'utilisateur pourquoi.
-
Vérifier les liens que le linter ne peut pas vérifier : les URL absolues et les ancres. Testez en cliquant ou expliquez ceux qui n'ont pas été vérifiés.
Résultat
- Le nouveau README.md ou la version mise à jour (affichez un résumé des différences pour les réécritures).
- Le résultat final du lint.
- Une courte liste des faits que vous n'avez pas pu vérifier et des espaces réservés que l'utilisateur doit remplir (GIF de démo, captures d'écran, chiffres de benchmark).
Règles de lint
| Règle | Niveau | Signification |
|---|---|---|
| title | erreur/avertissement | exactement un H1 |
| pitch | erreur/avertissement | une courte phrase sous le titre |
| badges | avertissement | aucun badge trouvé |
| install | erreur/avertissement | section d'installation (ou démarrage rapide), avec un bloc de code |
| quickstart | erreur/avertissement | section utilisation, démarrage rapide ou exemple, avec du code |
| code | erreur | aucun bloc de code du tout |
| scroll | avertissement | premier bloc de code après --max-scroll lignes (par défaut 60) |
| contributing, license | avertissement | section manquante |
| faq, toc | info | suggéré |
| alt-text | avertissement | image sans texte alternatif |
| broken-link | erreur | lien relatif vers un fichier manquant, ou lien vide |
| broken-anchor | erreur | lien #ancre (table des matières) qui ne correspond à aucun titre ou id/name HTML, en utilisant les règles de slug de GitHub |
| placeholder | avertissement | texte TODO, TBD ou lorem ipsum laissé |
Sortie 1 en cas d'erreur (et en cas d'avertissement avec --strict).