Comment écrire un bon README

Question

Je suppose que tout le monde a vu un README le fichier, mais je voudrais le guide définitif sur comment écrire un excellent README le fichier avec le moins de dépense d'énergie.

• Qu'est ce qu'un README le fichier?
• Que dois-je écrire?
• Exactement comment dois-je le formater?

Note de côté:

Comme un exemple qui répond à "OMG c'est un excellent README!" et "OMG ce fichier lisez-moi est inutile", j'ai posté un lien vers gnome-cups-manager Fichier lisez-moi, un commentaire. Le commentaire est maintenant supprimé en raison probablement des morts lien alors j'ai copié le contenu de cette gist.

Answer 1

Comme d'autres l'ont noté, README doit être simple et court, mais un bon README pouvez gagner du temps surtout si c'est pour quelque chose comme paramètre de ligne de commande d'analyse de la bibliothèque.

Voici ce que je pense qu'il devrait inclure:

• nom des projets et de tous les sous-modules et bibliothèques (parfois ils sont nommés différents et très déroutant pour les nouveaux utilisateurs)
• les descriptions de tous les le projet, et tous les sous-modules et bibliothèques
• 5-ligne extrait de code sur la façon dont il est utilisé (si c'est une bibliothèque)
• le droit d'auteur et les informations de licence (ou "LICENCE")
• l'instruction de saisir la documentation
• instructions pour installer, configurer et d'exécuter les programmes
• instruction pour attraper la dernière version du code et des instructions détaillées pour la construire (ou aperçu rapide et "Lire INSTALLER")
• liste des auteurs ou des "AUTEURS les plus Lus"
• instructions pour envoyer des rapports de bugs, demandes de fonctionnalités, soumettre des patchs, rejoignez la liste de diffusion, obtenir des annonces, ou de rejoindre l'utilisateur ou de la communauté de dev sous d'autres formes
• d'autres infos de contact (adresse e-mail, site web, nom de société, adresse, etc...)
• une brève histoire si c'est un remplacement ou une fourchette de quelque chose d'autre
• mentions légales (trucs de crypto)

Apache HTTP Server est un simple mais bonne README. Un autre bon j'ai trouvé en ligne disponible est de GNU Make est README.

Comme pour formatage, je dirais bâton à la Unix traditions autant que possible, et/ou utiliser markdown en particulier pour les projets github, ce qui rend le fichier README.md comme html.

• Les caractères ASCII seulement, si le fichier README est écrit en anglais
• l'écrire en anglais si possible, et de les expédier version traduite avec deux lettres de la langue extension de code comme README.ja
• De 80 caractères par ligne
• seule ligne vide entre les paragraphes
• les tirets sous les en-têtes
• retrait à l'aide de espace (0x20) pas d'onglet

Mettre tous ensemble...

Documentation
-------------

GNU make is fully documented in the GNU Make manual, which is contained
in this distribution as the file make.texinfo.  You can also find
on-line and preformatted (PostScript and DVI) versions at the FSF's web
site.  There is information there about ordering hardcopy documentation.

  http://www.gnu.org/
  http://www.gnu.org/doc/doc.html
  http://www.gnu.org/manual/manual.html 

---

Wikipedia définit comme:

Un fichier readme (ou lisez-moi) fichier contient des informations sur d'autres fichiers dans un répertoire ou d'archive et est très souvent distribué avec un logiciel informatique.

et il énumère le contenu suivant:

• instructions de configuration
• les instructions d'installation
• instructions de fonctionnement
• un fichier manifest
• droits d'auteur et licences information
• coordonnées du distributeur ou du programmeur
• bugs connus
• dépannage
• crédits et remerciements
• un changelog

Answer 2

Je pense que la plupart des fichiers readme sont trop verbeux. Un fichier lisez-moi est le premier fichier une personne devrait lire lors de la rencontre d'un arbre source, et il devrait être écrit comme une très brève introduction très basique pour le logiciel. Il doit contenir le nom du code, la version, éventuellement, date de la dernière mise à jour, et un très bref aperçu de haut niveau du logiciel (très haut niveau). Et c'est tout, d'autres que, éventuellement, les références à des fichiers qui contiennent d'autres renseignements qu'une personne pourrait être intéressé que les instructions d'installation (INSTALL), les auteurs (AUTEURS), ou de l'histoire (dans le ChangeLog ou ReleaseNotes).

Le fichier lisez-moi est une introduction. Elle se doit d'assumer le lecteur sait absolument rien sur le logiciel et doit fournir une brève introduction. Si les logiciels étaient un scénario, le fichier README serait le deuxième 10 slogan utilisé pour planter le script à un producteur. Si une personne a fini de lire les 10 premières lignes du frobnicator/README et ne sais pas si frobnicator est une bibliothèque de widgets, logiciel de comptabilité, ou d'un jeu vidéo, c'est que l'auteur de ce fichier a échoué.

Answer 3

C'est un fichier texte, le plus simple est la meilleure), appelé "README" (ou "readme" ou "lisez-moi", et possible avec un ".txt" extension si votre système d'exploitation vous fait) qui dit:

• Ce que c'est un fichier lisez-moi (y compris la version) à la fois un nom et une brève description
• Lorsque le fichier a été modifié
• Éventuellement: qui est responsable de ce désastre
• Éventuellement: informations de licence
• Lorsque vous devez vous tourner pour obtenir la chose décrite, si vous ne l'avez pas déjà
• Ce dont vous avez besoin pour exécuter ou de les utiliser
• Ce que vous devez savoir pour obtenir ce que ça va
• Où trouver le plus complet docs (le cas échéant)
• Autre chose qui me semble utile

Answer 4

J'ai également été à la recherche pour la mise en forme des lignes directrices sur les fichiers README, en particulier "traditionnel" avec le NOM, la DESCRIPTION, le SYNOPSIS, les AUTEURS sections (exemple de la page de manuel de GNUCHESS).

Un lien que j'ai trouvé est: Russ Documentation du Style:

Ces lignes directrices sont pour la documentation de la distribution de logiciels de logiciel open source. Ils sont applicables à C, Perl, Java et de projets, et des projets qui ne peuvent contenir des logiciels compilés. [...]
Toute demande doit contenir, au plus haut niveau, les documents suivants de fichiers: ... de LICENCE [...] NEWS [...] README [...] TODO
La documentation devrait au minimum inclure le NOM, le SYNOPSIS, DESCRIPTION, EXEMPLES, l'AUTEUR ou les AUTEURS, le droit d'AUTEUR et de LICENCE sections dans l'ordre. Si elle a des options de ligne de commande, il devrait également être une des OPTIONS de la section immédiatement à la suite de la DESCRIPTION de l'article. Ceux-ci devraient tous être =head1 sections dans le module.

Maintenant que POD est mentionné, il est synonyme de Plain Old Documentation de style pour Perl logiciel.J'ai trouvé aussi des Standards de programmation GNU - 6.9 Pages de Man, mais il n'a pas beaucoup parlé à propos de la documentation de style.

Je pensais que j'avais d'autres ressources similaires trouvé, mais je ne peux pas les trouver dans ma session actuelle du navigateur :/ Si je trouve quelque chose de nouveau, je vais être sûr de mettre à jour ce post...

Cheers!

Answer 5

C’est les instructions pour la personne qui utilise votre « produit » pour obtenir l’ai installé et savoir où trouver des informations plus détaillées. Si fournir quelques renseignements de base supplémentaire peut aider avec ça, alors qui comprennent aussi bien. Il devrait être très succinct.