Un référentiel public peut être difficile à évaluer s'il s'ouvre sur des dossiers inexpliqués ou sur une commande de configuration obsolète. Un README concis réduit ces frictions et permet à un réviseur de se concentrer sur le code et les décisions.
Inclure les essentiels
- Indiquez ce que fait le projet et à qui il s’adresse.
- Répertoriez les prérequis et les étapes de configuration testées dans l'ordre dans lequel un nouveau contributeur doit les exécuter.
- Décrivez les fonctionnalités clés, les limitations connues et comment exécuter des tests ou afficher une démo.
Vérifiez les instructions à partir d'un bon départ
Suivez vos propres étapes de configuration dans une nouvelle caisse ou un répertoire temporaire. Remplacez les chemins spécifiques à la machine, supprimez les clés privées et les données personnelles et assurez-vous que les commandes correspondent aux scripts actuels du référentiel.
Ajoutez une capture d'écran ou une note d'architecture uniquement lorsqu'elle clarifie l'expérience. Un petit projet avec des instructions précises est plus utile qu'un grand README plein de revendications que le code ne prend pas en charge.