Un README devrait aider un nouveau lecteur à faire le premier pas utile. Il n’est pas nécessaire d’expliquer chaque détail de mise en œuvre avant de pouvoir déterminer ce que fait le projet ou s’il est pertinent pour lui.

Diriger avec le résultat

Décrivez ce que fait le projet, à qui il s'adresse et ses limites importantes. Un exemple concret est plus utile qu’une liste d’adjectifs. Placez une capture d'écran fonctionnelle ou un exemple de résultat en haut lorsque cela aide à expliquer le but.

Indiquez ensuite les prérequis : système d'exploitation, version d'exécution et services requis. Distinguez les intégrations facultatives de ce qui est nécessaire pour démarrer. Ne laissez pas un lecteur découvrir une exigence essentielle à mi-chemin de l'installation.

Donnez un chemin complet vers le succès

Écrivez les étapes de configuration dans l’ordre où elles doivent se produire. Expliquez où les commandes doivent être exécutées et à quoi ressemble un résultat réussi. Utilisez clairement la configuration des espaces réservés et n’incluez jamais de véritables informations d’identification dans l’exemple.

Testez les instructions à partir d’une caisse propre ou d’un point de départ équivalent. Une commande qui fonctionne uniquement parce que votre ordinateur est équipé d'un outil non documenté constitue une lacune dans la documentation. Conservez les variantes facultatives sous le chemin pris en charge le plus simple.

Rendre la prochaine étape facile à trouver

Ajoutez les commandes courantes pour exécuter, vérifier et mettre à jour le projet. Créez un lien vers une documentation plus approfondie au lieu de placer chaque sujet spécialisé dans la section d'ouverture. Incluez le lieu pris en charge pour signaler les problèmes et la licence, le cas échéant.

Utilisez MeatPad pour modifier le README à côté des fichiers du projet, puis vérifiez son rendu Markdown dans la destination. Suivez les liens et inspectez les images avec les chemins réels du référentiel. Lorsque la configuration change, mettez à jour le README dans le même changement afin que les instructions de première exécution décrivent la version que les utilisateurs reçoivent.

Sources et détails du produit

Commencez par une note. MeatPad donne aux notes, Markdown et aux fichiers de projet un espace de travail local sur votre Mac, sans nécessiter de compte.

Explorez MeatPad →