Repository: hackergrrl/art-of-readme
Branch: master
Commit: dc67cd5376a0
Files: 8
Total size: 164.9 KB
Directory structure:
gitextract_lldhirn_/
├── README-de-DE.md
├── README-es-ES.md
├── README-fr.md
├── README-ja-JP.md
├── README-pt-BR.md
├── README-zh-TW.md
├── README-zh.md
└── README.md
================================================
FILE CONTENTS
================================================
================================================
FILE: README-de-DE.md
================================================
# Die Kunst des README
*Dieser Artikel wurde aus dem [Englischen](README.md) übersetzt.*
*Dieser Artikel kann auch auf [Chinesisch](README-zh.md),
[Brasilianisches Portugiesisch](README-pt-BR.md),
[Spanisch](README-es-ES.md) und [Französisch](README-fr.md) gelesen werden.*
## Etymologie
Woher stammt der Begriff "README"?
Die Bezeichnung geht *mindestens* zurück auf die 70er Jahre
[und den PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html),
auch wenn es sogar noch weiter zurückliegen könnte, zu den Tagen, als
informative Papiernotizen auf einen Stapel Lochkarten gestapelt wurden
mit „LIES MICH!” bekritzelt, um ihren Zweck zu beschreiben.
Ein Leser<sup>[1](#footnote-1)</sup> schlug vor, dass der Title README eine
humorvolle Anspielung auf
*Alice im Wunderland* von Lewis Caroll seien könnte, in der es
einen Trank und einen Kuchen mit der Bezeichung *"DRINK ME"* beziehungsweise
*"EAT ME"* gibt.
Das Muster, das README komplett in Großbuchstaben erscheint, ist eine
konsistente Facette durch die Geschichte. Nicht nur dank der visuellen
Hervorhebung durch das Benutzen von Majuskeln, sondern auch dadurch, dass
UNIX-Systeme Großbuchstaben vor Kleinbuchstaben sortieren würden, was die
README bequemerweise vor den Rest des Ordnerinhalts
platzierte<sup>[2](#footnote-2)</sup>.
Die Absicht ist klar: *"Dies ist wichtige Information für den Nutzer, die
gelesen sollte, bevor weitergemacht wird."* Lasst uns zusammen erkunden,
was "wichtige Informationen" in der heutigen Moderne ausmacht.
## Für Ersteller, für Konsumierende
Dies ist ein Artikel über READMEs. Darüber, was sie tun, warum sie unbedingt
notwendig sind und wie sie gut erstellt werden können.
Dies ist für Ersteller von Modulen geschrieben, da es die Aufgabe eines solchen
ist, etwas zu schaffen, dass überdauert. Es ist eine inhärente Motivation,
selbst wenn der Autor keine Absicht hat, ihre Arbeit zu teilen. Nach sechs
Monaten wird ein Modul ohne Dokumentation wie neu und unbekannt aussehen.
Dies ist ebenso für Konsumierende von Modulen geschrieben, da jeder Auto auch
ein Nutzer von Modulen ist. Node.js hat einen sehr gesunden Grad von
Interdependenz: niemand lebt wirklich am Fuße des Abhängigkeitsbaums.
Auch wenn es sich auf Node.js fokussiert, behauptet der Autor, dass die
Lektionen sich genauso gut auf andere Programmierumgebungen anwenden lassen.
## Viele Module: einige gut, andere schlecht
Das Node.js-Ökosystem basiert auf seinen Modulen. [npm](https://npmjs.org) ist
die Magie dahinter, die es alles *vorantreibt*. Innerhalb einer Woche werten
Node.js-Entwickler Dutzende Module aus, ob sie sie für ihre Projekte nutzen
sollen. Damit wird täglich eine Menge Macht freigesetzt, die nur darauf wartet
genutzt zu werden, indem `npm install` geschrieben wird.
Wie andere sehr zugängliche Ökosysteme auch, schwankt die Qualität. npm
macht das Beste daraus, all diese Module nett zu verpacken und weit zu
verteilen. Die gefundenen Werkzeuge unterscheiden sich jedoch ziemlich:
einige sind brandneu, andere angestaubt oder kaputt und wieder andere irgendwo
dazwischen. Es gibt sogar welche, von denen wir gar nicht wissen, was sie tun!
Für einige Module kann das in Form ungenauer oder wenig hilfreicher Namen
annehmen (was wohl das `fudge` Modul tut?), andere haben keine Dokumentation,
Tests, Kommentare im Quellcode oder unverständliche Funktionsnamen.
Viele haben keinen aktiven Instandhalter. Falls ein Modul keinen Menschen mehr
hat, der Fragen beantwortet und erklärt, was ein Modul macht, kombiniert mit
fehlenden Überbleibseln von Dokumentation, dann wird das Modul ein bizarres
Artefakt eines Aliens, unbenutzbar und unverständlich für die
Archäologie-Hacker von morgen.
Wo landen die Module, die eine Dokumentation haben, auf dem Qualitätsspektrum?
Manchmal handelt es sich nur um einen Einzeiler: `"sortiert Nummern nach ihren
Hex-Werten"`. Vielleicht ist es ein Beispielcode-Schnippsel. Beides sind
besser als gar nichts, aber sie tendieren dazu, in das Worst-Case Szenario
einer modernen Modul-Höhlenforschung zu resultieren: Den Quellcode
durchforsten, um zu versuchen und zu verstehen, wie es tatsächlich
funktioniert. Das Schreiben hervorragender Dokumentation zeichnet sich dadurch
aus, dass der Nutzer aus dem Quellcode ferngehalten wird, indem die Anleitungen
ausreichend genug sind, um die wundervollen Abstraktionen zu genießen, die das
Modul bereitstellt.
Node.js hat ein "großes" Ökosystem: Es besteht im Wesentlichen aus einer
sehr langen Liste von unabhängigen mach-eine-Sache-gut Modulen und nicht mehr.
Es gibt [Ausnahmen](https://github.com/lodash/lodash), aber von diesen
kleineren Lehnsgütern abgesehen sind es die Einzweck-Gutsherren, die aufgrund
ihrer schieren Anzahl das Node.js-Königreich beherrschen.
Diese Situation hat eine natürliche Konsequenz: Es kann schwer sein,
*hochwertige* Module zu finden, die genau das machen, was du willst.
**Das ist in Ordnung**. Wirklich. Eine niedrige Eintrittsbarriere und das
Auffindbarkeits-Problem sind unendlich besser als ein Kulturproblem, bei dem
nur die wenigen Privilegierten teilnehmen dürfen.
Darüberhinaus lässt sich Auffindbarkeit -- wie wir herausfinden werden --
einfacher adressieren.
## Alle Straßen führen zur README.md
Die Node.js Gemeinschaft hat auf die Herausforderung der Auffindbarkeit in
verschiedenen Weisen reagiert.
Einige erfahrene Node.js-Entwickler haben sich zusammengetan, um eine
[kuratierte Liste](https://github.com/sindresorhus/awesome-nodejs) hochwertiger
Module zu erstellen.
Entwickler nutzen ihre langjährige Erfahrung beim Untersuchen von Hunderten
verschiedener Module, um mit Neulingen die *crème de la crème* zu teilen:
die besten Module in jeder Kategorie.
Dies kann auch in Form von RSS-Feeds und Mailinglisten geschehen, die neue
Module vorstellen, die von vertrauenswürdigen Mitgliedern der Community als
nützlich betrachtet werden.
Was ist mit dem sozialen Graphen? Diese Idee regte die Erstellung von
[node-modules.com](http://node-modules.com/) an, einem Ersatz der npm-Suche,
die GitHub's sozialen Graphen verwendet, um Module zu finden, die deine Freunde
mögen oder erstellt haben.
Natürlich hat npm auch eine eingebaute [Suche](https://npmjs.org):
ein sicherer Standard und der übliche Einstiegspunkt für neue Entwickler.
Egal welcher Ansatz, unabhängig davon, ob ein Modul-Höhlenforscher die
Moduluntergründe von [npmjs.org](https://npmjs.org),
[github.com](https://github.com) oder anderswo betritt, der potentielle Nutzer
wird schließlich deine README zu sehen bekommen. Da sich deine Nutzer
unausweislich hier wiederfinden werden, stellt sich die Frage, was du machen
kannst, um ihren ersten Eindruck maximal effektiv zu mcahen?
## Professionelle Modul-Höhlenforschung
### Die README: Alles aus einer Hand
Die README ist der erste -- und vielleicht einzige -- Blick eines Modulnutzers
in dein Werk. Der Nutzer erwartet, dass ein Modul ihre Bedürfnisse erfüllt,
also must du genau erklären, was für ein Problem dein Modul löst und wie
effektiv es dabei ist.
Deine Aufgabe ist es,
1. zu erklären, was es ist (mit Kontext)
2. zu zeigen, wie es in Aktion aussieht
3. zu zeigen, wie es genutzt wird
4. alle weiteren relevante Details aufzuzählen
Dies ist *deine* Aufgabe. Es liegt an den Modulersteller zu beweisen, dass
ihre Arbeit ein glänzender Edelstein im Meer von schludrigen Modulen ist.
Da so viele Entwickleraugen zuerst die README finden werden, ist Qualität hier
dein öffentlichkeitswirksames Maß deiner Arbeit.
### Kürze
Das Fehlen einer README ist eine starke Warnsignal, aber auch eine lange
README ist kein Indikator von hoher Qualität. Die ideale README ist so kurz
wie es geht, aber nicht kürzer. Ausführliche Dokumentation ist gut -- erstelle
separate Seiten dafür! -- aber halte deine README prägnant.
### Aus der Vergangenheit lernen
Es heißt, dass jene, die nicht aus ihrer Vergangenheit lernen, dazu verdammt
sind, die Fehler zu wiederholen. Entwickler haben bereits seit einigen Jahren
Dokumentation geschrieben. Es wäre eine Verschwendung, nicht ein wenig darauf
zurückzublicken und nachzuschauen, was die Leute vor Node.js gemacht haben.
Perl, trotz aller Kritik, die es erfährt, ist in einigen Weisen der geistige
Großvater von Node.js. Beides sind High-Level Skriptsprache, übernehmen viele
UNIX-Idiome, befeuern große Teile des Internets und beide besitzen ein reiches
Modul-Ökosystem.
Es stellt sich heraus, dass die
[Mönche der Perl-Community](http://perlmonks.org) der tatsächlich viel
Erfahrung im Schreiben von
[hochqualitativen READMEs](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm)
erworben haben. CPAN ist eine wundervolle Ressource, die es wert ist,
durchgelesen zu werden, um mehr von einer Gemeinschaft zu lernen, die durchweg
hochkalibrige Dokumentation geschrieben hat.
### Keine README? Keine Abstraktion
Ohne README werden Entwickler den Quellcode betrachten müssen, um ihn zu
verstehen.
Die Perl-Mönche haben hierzu eine Weisheit zu teilen:
> Deine Dokumentation ist dann vollständig, wenn jemand dein Modul nutzen kann,
> ohne jemals auf den Quellcode schauen zu müssen. Das ist sehr wichtig. Es
> ermöglicht es dir, die dokumentierte Schnittstelle deines Moduls von dessen
> Implementierung zu trennen (gut). Das ist gut, weil es bedeutet, dass du
> frei bist, die Interna deines Moduls zu ändern, solange die Schnittstelle
> die gleiche bleibt.
>
> Zur Erinnerung: Die Dokumentation, nicht der Quellcode, bestimmt darüber,
> was ein Modul macht.
-- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### Schlüsselelemente
Sowie eine README gefunden wurde, überfliegt der mutige Modul-Höhlenforscher es,
um festzustellen, ob es die Bedürfnisse des Entwicklers abdeckt. Im
Wesentlichen handelt es sich dabei um eine Reihe von Problemen des
Musterabgleichs, welches das Gehirn lösen muss, wobei jeder Schritt den
Entwickler tiefer in das Modul und dessen Details führt.
Sagen wir zum Beispiel, meine Suche für ein Modul zur 2D-Kollisionserkennung
führt mich zu
[`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb). Ich
beginne damit, es von oben nach unten zu durchforsten:
1. *Name* -- am besten selbsterklärend. `collide-2d-aabb-aabb` klingt
vielversprechend, auch wenn es annimmt, dass ich weiß, was "aabb" ist. Wenn
der Name zu vage oder unbezogen klingt, kann das ein Signal sein, woanders
weiterzusuchen.
2. *Einzeiler* -- ein Einzeiler zur Beschreibung des Moduls kann nützlich sein,
um eine Idee davon zu bekommen, was das Modul in etwa macht.
`collide-2d-aabb-aabb` sagt, dass es
> Bestimmt, ob eine sich bewegende Achsen-ausgerichtete Begrenzungs-Box
> (AABB) mit anderen AABBs kollidiert.
Fantastisch: es definiert AABB und was das Modul macht. Jetzt zum Abschätzen,
wie gut es in meinen Code passen wird:
3. *Benutzung* -- anstatt sich direkt in die API-Dokumentation zu vertiefen,
wäre es toll zu sehen, wie das Modul in Aktion aussieht. Ich kann schnell
bestimmen, ob das Beispiel-JavaScript den gewünschtem Stil und Problem
entspricht. Die Leute haben viele Meinungen dazu, wie Dinge wie
Promises/Callbacks und ES6 aussehen sollten. Falls es den Vorstellungen
entspricht, dann kann ich mit mehr Details fortfahren.
4. *API* -- der Name, die Beschreibung und die Benutzung des Moduls klingen
allesamt vielversprechend für mich. Ich bin an dieser Stelle sehr dazu
geneigt, das Modul zu benutzen. Ich muss nur noch das API überfliegen, um zu
sehen, ob es genau das macht, was ich brauche und werde es dann leicht in
meine Codebase integrieren. Der Abschnitt zum API muss daher die Objekte und
Funktionen des Moduls, ihre Signaturen, Rückgabewerte, Callbacks und Events
im Detail beschreiben. Typen sollten einbezogen werden, wenn sie nicht
offensichtlich sind. Warnungen sollten klar gemacht werden.
5. *Installation* -- wenn ich bis hierhin gelesen habe, bin ich bereit, dass
Modul zu installieren. Falls die Installationsbeschreibung vom Standard
abweicht, sollte es hier stehen, selbst wenn es nur ein reguläres
`npm install` ist, würde ich das gerne erwähnt sehen. Ständig fangen neue
Nutzer mit Node.js an, so dass ein Link zur npmjs.org und ein
Installationsbefehl ihnen die Ressourcen an die Hand gibt, um herauszufinden,
wie Node.js-Module funktionieren.
6. *Lizenz* -- viele Module platzieren dies ganz am Ende, aber es könnte weiter
oben besser aufgehoben sein; du wirst ein Modul wohl sehr schnell
ausschließen, wenn die Lizenz mit deiner Arbeit unkompatibel ist. Generell
tendiere ich zu MIT/BSD/X11/ISC-Varianten. Falls du eine non-permissive
Lizenz hast, platziere sie ganz am Anfang, um Verwirrung zu vermeiden.
## Wahrnehmungstrichter
Die Reihenfolge oben wurde nicht zufällig gewählt.
Nutzer von Modulen benutzen viele, und sie müssen sich viele Module anschauen.
Nachdem du Hunderte von Modulen betrachtet hast, wirst du bemerken, dass der
Verstand von bestimmten Mustern profitiert.
Du wirst außerdem anfangen, eine eigene persönliche Heuristik zu entwickeln,
welche Informationen du brauchst und welche Warnsignale ein Modul sehr schnell
disqualifizieren.
Daher ist es für eine README vorteilhaft, folgendes zu besitzen:
1. ein vorhersehbares Format
2. das Vorhandensein bestimmter Schlüsselelemente
Du musst nicht *dieses* Format nutzen, aber versuche konsistent zu sein, um
deinen Nutzern wertvolle Runden der Erkenntnis zu ersparen.
Die hier gewählte Reihenfolge wird auch liebevoll als "Wahrnehmungstrichter"
bezeichnet und kann sich wie ein Trichter vorgestellt werden, der aufrecht
gehalten wird, wobei das breite Ende die gröbsten relevanten Details beinhaltet
und nach unten hin immer spezifischer wird für die Leser, die an deiner Arbeit
interessiert genug sind, um so weit unten im Dokument anzugelangen. Das Ende
kann dann für Details reserviert werden für diejenigen, die mehr an dem
tieferen Kontext der Arbeit interessiert sind (Hintergrund, Danksagungen,
Quellenangaben usw.).
Wieder einmal haben die Perlmönche eine Weisheit zu diesem Thema zu teilen:
> Der Detaillevel in Dokumentation von Perlmodulen reicht üblicherweise von
> weniger detailliert zu mehr detailliert. Der SYNOPSIS-Abschnitt sollte ein
> Minimal-Beispiel zur Benutzung beinhalten (vielleicht so klein wie eine Zeile
> Code; überspring die ungewöhnlichen Fälle oder alles, dass nicht von den
> meisten Nutzern gebraucht wird); die DESCRIPTION sollte dein Modul in groben
> Zügen beschreiben, normalerweise in wenigen Abschnitten; mehr Details zu den
> Routinen oder Methoden deines Moduls, längere Codebeispiele oder anderes
> tiefergehendes Material sollte in darauffolgenden Abschnitten kommen.
>
> Idealerweise sollte jemand, der nur wenig mit deinem Modul vertraut ist,
> seine Erinnerung auffrischen können, ohne auf "Bild ab" drücken zu müssen.
> Mit weiterem Voranschreiten durch das Dokumente, sollten deine Leser nach
> und nach tieferes Wissen erhalten.
> -- aus `perlmodstyle`
## Sorge dich um die Zeit der Leute
Fantastisch; die Reihenfolge dieser Schlüsselelemente sollte dadurch bestimmt
werden, wie schnell sie es jemanden erlaubt, vorzeitig dein Modul zu
verwerfen.
Das klingt rau, stimmt's? Aber denk drüber nach: es ist nicht deine Aufgabe,
sowie du sie mit einem optimalen Altruismus erfüllst, den Leuten deine Arbeit
zu "verkaufen". Sondern sie dein Werk so objektiv wie möglich auswerten zu
lassen, um zu entscheiden, ob es ihre Bedürfnisse erfüllt oder nicht -- und
nicht etwa, sagen wir, die Anzahl der Downloads oder Nutzer zu maximieren.
Diese Denkweise spricht nicht jeden an; sie verlangt das eigene Ego außen vor
zu lassen und die Arbeit soweit wie möglich für sich selbst sprechen zu lassen.
Dein einziger Auftrag ist es, sein Versprechen so genau wie möglich zu
beschreiben, so dass Modul-Höhlenforscher entweder deine Arbeit, sofern sie
passt, benutzen, oder sich nach etwas anderem umsehen können.
## Zu den Waffen!
Schreite voran, mutiger Modul-Höhlenforscher, und mach deine Arbeit auffindbar
und nutzbar durch exzellente Dokumentation!
## Bonus: andere gute Praktiken
Außer den Schlüsselpunkten dieses Artikels gibt es noch andere Praktiken, die
du anwenden (oder nicht anwenden) kannst, um die Qualitätsleiste deiner
README zu erhöhen und dessen Nützlichkeit für andere zu maximieren:
1. Überleg dir, ob du einen Abschnitt **Hintergrund** einfügen willst, falls
dein Modul auf wichtigen, aber nicht sehr bekannten Abstraktionen oder
anderen Ökosystemen beruht. Die Funktion von
[`bisecting-between`](https://github.com/noffle/bisecting-between) ist nicht
jedem sofort klar anhand des Namens, so das es einen ausführlichen Abschnitt
*Hintergrund* hat, um die großen Konzepte zu definieren und zu verlinken,
sowie die Abstraktionen zu erklären, die jemand verstehen muss, um es zu
benutzen. Dies ist auch ein toller Platz, um die Motivation hinter dem
Modul zu erklären, falls ähnliche Module bereits auf npm existieren.
2. Verlinke viel! Falls du über andere Module, Ideen oder Personen sprichst,
verlinke die Referenz, so dass Besucher einfach dein Module und die Ideen
dahinter verstehen können. Wenige Module existieren in einem Vakuum: die
ganze Arbeit beruht auf anderen Werken, also zahlt es sich aus, dass Nutzer
die Geschichte und Inspiration deines Moduls folgen können.
3. Schließe Informationen über Typen von Argumenten und Rückgabewerten ein,
sofern diese nicht offensichtlich sind. Bevorzuge Konvention wo immer
möglich. `cb` bedeutet wahrscheinlich callback-Funktion, `num` bezeichnet
wohl ein `Number` usw.).
4. Führe Beispielcode aus dem Bereich **Benutzung** als Datei in deinem Repo
-- vielleicht als `example.js`. Es ist klasse, README code zu haben, den
Nutzer tatsächlich ausführen können, falls sie das Repository klonen.
5. Sei bedachtsam mit dem Nutzen von Abzeichen. Sie können leicht
[missbraucht](https://github.com/angular/angular) werden. Sie können auch
Grundlage für Nebensächlichkeiten (Bikeshedding) und endlosen Debatten
werden. Sie fügen visuellen Störungen zu deiner README hinzu und
funktionieren oft nur, wenn der Nutzer dein Markdown im Webbrowser liest, da
die Bilder oft woanders im Internet gehostet werden.
Für jedes Abzeichen überlege dir: "Was ist der tatsächliche Wert, den dieses
Abzeichen dem üblichen Betrachter der README bringt?" Hast du ein
CI-Abzeichen, um den Status des Builds / Tests anzuzeigen? Dieses Signal
würde die relevanten Gruppen eher erreichen, indem den Instandhaltern eine
E-Mail geschickt oder ein Issue erstellt wird. Bedenke immer das Publikum
der Daten in deiner README und frage dich selber, ob es einen Fluss für
diese Daten gibt, die das gewünschte Publikum besser erreicht.
6. API-Formatierung hat das Potential, sich in Nebensächlichkeiten zu
verlieren. Benutze das Format, von dem du denkst, es ist am klarsten, aber
stelle sicher, das dein Format folgende wichtige Feinheiten ausdrückt:
a. welche Parameter sind optional, sowie ihre Standardwerte
b. Typinformationen, sofern nicht aufgrund von Konventionen offensichtlich
c. für `opts` Objekt-Parameter, alle akzeptierten Schlüssel-Wert-Paare
d. schrecke nicht davor zurück, ein winziges Beispiel der Benutzung einer
API-Funktion zu geben, sofern es nicht offensichtlich oder im Abschnitt
**Benutzung** behandlet wurde.
Dies kann aber auch ein starker Hinweis darauf sein, dass die Funktion zu
komplex ist und refactort, in kleinere Funktionen aufgebrochen oder
komplett entfernt werden muss
e. verlinke spezielle Terminologie! In Markdown kannst du
[Fußnoten](https://daringfireball.net/projects/markdown/syntax#link) am
Ende deines Dokuments einfügen, so dass das erneute Verweisen von ihnen
sehr billig ist. Einige meiner persönlichen Präferenzen hinsichtlich
API-Formatierung lassen sich
[hier](https://github.com/noffle/common-readme/blob/master/api_formatting.md)
finden
7. Falls dein Modul sich aus einer Sammlung zustandsloser Funktionen
zusammensetzt, kann der Abschnitt **Benutzung** als
[Node REPL session](https://github.com/noffle/bisecting-between#example) von
Funktionsaufrufen und -ergebnissen vielleicht den Gebrauch klarer ausdrücken
als das Ausführen einer Datei.
8. Falls dein Modul ein CLI (command line interface) bereitstellt anstelle
(oder zusätzlich zu) einem programmatischen API, zeige Nutzungsbeispiele als
Aufrufe von Befehlen und ihrer Ausgabe. Falls du eine Datei erstellst oder
bearbeitest, `cat` sie, um den Unterschied davor und danach zu demonstrieren.
9. Vergiss nicht, [Keywords](https://docs.npmjs.com/files/package.json#keywords)
in der `package.json` zu benutzen, um Modul-Höhlenforscher an deine Pfote zu
leiten.
10. Je mehr du dein API veränderst, desto mehr Arbeit musst du darauf
verwenden, deine Dokumentation zu aktualisieren -- die Implikation hier ist,
dass du dein API klein halten und früh konkret definieren solltest.
Anforderungen ändern sich über die Zeit, aber anstatt Annahmen von
vornherein in das API deiner Module zu packen, hebe sie eine
Abstraktionsebene höher: dem Modul selber. Sofern sich die Änderungen
*tatsächlich* ändern und 'mach-eine-konkrete-Sache' nicht länger Sinn
ergibt, erstelle ein neues Modul, dass die Aufgabe erledigt. Das
'mach-eine-konkrete-Sache'-Modul bleibt weiterhin gültig und ein wertvolles
Modell für das npm-Ökosystem, und deine Kurskorrektur kostet dich nichts
außer einer einfachen Ersetzung eines Moduls mit einem anderen.
11. Schlussendlich, erinnere dich bitte, dass deine Versionskontroll-Repository
und die README darin dein [repository host](https://github.com) überleben
wird und ebenso alles, worauf du einen Link setzt -- insbesondere Bilder --
so *inkludiere* alles, was wesentlich ist für künftige Nutzer, um deine
Arbeit zu verstehen.
## Bonus: *common-readme*
Nicht zufälligerweise wird das vorgestellte Format auch von
[**common-readme**](https://github.com/noffle/common-readme) verwendet, einer
Sammlung von README-Richtlinien und handlichen Kommandozeilen-Generatoren.
Falls dir gefällt, was hier geschrieben steht, kannst du etwas Zeit beim
Schreiben von README mit `common-readme` sparen. Du wirst tatsächliche
Beispiele von Modulen in diesem Format dort finden.
Du magst vielleicht auch
[standard-readme](https://github.com/richardlitt/standard-readme), was ein
strukturierter, linearer Ansatz einer üblichen README-Formats darstellt.
## Bonus: Musterbeispiele
Theorie ist gut und schön, aber wie sehen hervorragende READMEs aus? Dies sind
einige Beispiele, von denen ich denke, die die Prinzipien diesen Artikels gut
verinnerlichen:
- https://github.com/noffle/ice-box
- https://github.com/substack/quote-stream
- https://github.com/feross/bittorrent-dht
- https://github.com/mikolalysenko/box-intersect
- https://github.com/freeman-lab/pixel-grid
- https://github.com/mafintosh/torrent-stream
- https://github.com/pull-stream/pull-stream
- https://github.com/substack/tape
- https://github.com/yoshuawuyts/vmd
## Bonus: Die README-Checkliste
Eine hilfreiche Checkliste, um abzuschätzen, wie gut deine README vorankommt:
- [ ] Einzeiler, der den Zweck deines Moduls ausdrückt
- [ ] Nützlicher Hintergrund-Kontext und Links
- [ ] Potenziell unbekannte Begriffe verlinken auf informative Quellen
- [ ] Klare, **lauffähige** Beispiele der Anwendung
- [ ] Installationsanleitung
- [ ] Ausführliche API-Dokumentation
- [ ] Ausführen des [Wahrnehmungstrichters](https://github.com/noffle/art-of-readme#cognitive-funneling)
- [ ] Warnmeldungen und Einschränkungen werden im Voraus erwähnt
- [ ] Verlässt sich nicht auf Bilder, um kritische Informationen zu vermitteln
- [ ] Lizenz
## Über den originalen Autor
Ich bin [noffle](http://blog.eight45.net/about/). Ich bin dafür bekannt zu
[bloggen](http://blog.eight45.net), [tweeten](https://twitter.com/noffle), und
zu [hacken](https://github.com/noffle).
Dieses kleine Projekt begann damals im Main in Berlin bei der squantconf, wo
ich mich damit beschäftigt habe, wie Perl-Mönche ihre Dokumentation schreiben
und mich ebenso über den Stand der READMEs im Node.js-Ökosystem beschwert habe.
Das hat mich dazu gebracht,
[common-readme](https://github.com/noffle/common-readme) zu erstellen.
Der Abschnitt zu "README Tipps" floss allerdings mit Tipps über, so dass ich
mich entschied, diese in einem Artikel zu sammeln, wie READMEs geschrieben
werden. So wurde die Kunst des README geboren!
Du kannst mich unter `noffle@eight45.net` oder im Freenode IRC in `#eight45`
erreichen.
## Zum Weiterlesen
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## Fußnoten
1. <a name="footnote-1"></a>Danke,
[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)!
2. <a name="footnote-2"></a>Siehe [Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html).
Die meisten Systeme heutzutage werden jedoch nicht Großbuchstaben vor
Kleinbuchstaben sortieren, so dass sich die Nützlichkeit der Konvention
auf die visuelle Hervorhebung durch die Nutzung der Großbuchstaben
beschränkt.
## Danksagung
Ein inniger Dank an dich, [@mafintosh](https://github.com/mafintosh) und
[@feross](https://github.com/feross) für die Ermunterung, die ich brauchte, um
diese Idee umzusetzen und anzufangen zu schreiben!
Danke auch an die folgenden großartigen Leser, die Fehler bemerkt und mir PRs
gesendet haben :heart: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
Dank an [@qihaiyan](https://github.com/qihaiyan) für das Übersetzen der Kunst
des README ins Chinesische! Die folgenden Nutzer haben auch Beiträge
eingebracht:
- [@BrettDong](https://github.com/brettdong) für das Revidieren der Punktierung
in der chinesischen Version.
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
Dank an [@lennonjesus](https://github.com/lennonjesus) für das Übersetzen der
Kundes des README in Brasilianisches Portugiesisch! Die folgenden Nutzer haben
auch Beiträge eingebracht:
- [@rectius](https://github.com/rectius)
Dank an [@jabiinfante](https://github.com/jabiinfante) für das Übersetzen der
Kunst des README ins Spanisch!
Dank an [@Ryuno-Ki](https://github.com/Ryuno-Ki) für das Übersetzen der Kunst
des README ins Deutsche! Die folgenden Nutzer haben auch Beiträge eingebracht:
- [@randomC0der](https://github.com/randomC0der)
Dank an [@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro) und
[@Ruben Madelaine](https://github.com/Ruben-Madelaine)
für das Übersetzen der Kunst des README ins Französisch!
Abschließend dank an alle für ihr Feedback! Bitte teilt eure Kommentare
[als issue](https://github.com/noffle/art-of-readme/issues)!
## Pull requests willkommen!
Einen Fehler entdeckt? Irgendetwas ergibt keinen Sinn? Sende mir einen
[pull request](https://github.com/noffle/art-of-readme/pulls)! Bitte vermeide
stilistische Änderungen -- sie werden wahrscheinlich nicht angenommen. Danke!
## Lizenz
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
================================================
FILE: README-es-ES.md
================================================
# El arte del README
*Este artículo ha sido traducido desde el [inglés](README.md) y tambien lo
puedes encontrar en [chino](README-zh.md),
[portugués brasileño](README-pt-BR.md), [alemán](README-de-DE.md)
o [Francés](README-fr.md).*
## Etimología
¿De dónde viene el término "README"?
La nomenclatura se remonta *por lo menos* a la década de los 70's, incluso
podría remontarse a los días de las notas de papel informativas situadas sobre
tarjetas perforadas donde encontramos "READ ME" (¡LEEME!) garabateado por
encima, describiendo así su uso.
Un lector<sup>[1](#footnote-1)</sup> ha sugerido que el título README puede ser
un guiño a *Las aventuras de Alicia en el país de las maravillas* de Lewis
Carroll, donde una poción y un pastel están etiquetados como *"BÉBEME"* y
*"CÓMEME"*, respectivamente.
El patrón README escrito por completo en mayúsculas ha sido constante a lo
largo de la historia. Además de la sorpresa visual de utilizar las mayúsculas,
los sistemas UNIX ordenan los caracteres en mayúsculas antes que en minúsculas,
acomodando convenientemente el archivo README antes que el resto del contenido
del directorio<sup>[2](#footnote-2)</sup>.
La intención es clara: *"ésta es información importante que el usuario debe
leer antes de continuar"*. Vamos a explorar juntos qué constituye la
"información importante" en estos tiempos modernos.
## Para creadores, para consumidores
Este es un artículo acerca de los archivos README. Sobre qué es lo que hacen,
por qué son absolutamente necesarios y cómo desarrollarlos correctamente.
Esto está escrito para creadores de módulos. Como constructores de módulos,
nuestro trabajo es crear algo que perdure en el tiempo. Esta es una motivación
inherente, incluso si el autor no tiene intención de compartir su trabajo. Una
vez que pasan 6 meses, un módulo sin documentación comienza a parecer nuevo y
desconocido.
Esto también está escrito para consumidores de módulos, ya que, todo autor de
módulos es también un consumidor de módulos. Node.js tiene un grado muy sano de
interdependencias: nadie está en lo más bajo del árbol de dependencias.
A pesar de estar centrado en Node.js, el autor sostiene que la lección puede
ser aplicada igual de bien a otros ecosistemas de programación.
## Muchos módulos: unos buenos, unos malos
El ecosistema de Node.js está sostenido gracias a sus módulos.
[npm](https://npmjs.org) es la magia
que hace que todo *funcione*. Durante una semana cualquiera, un desarrollador
de Node.js evalúa docenas de módulos para incluir en sus proyectos. Esto
significa utilizar muchísimo poder a diario, es tan rápido que basta con
ejecutar `npm install`.
Como cualquier ecosistema extremadamente accesible, la barra de calidad puede
variar. npm funciona empaquetando y distribuyendo estos módulos ampliamente.
Sin embargo, las herramientas que nos encontramos son muy variadas: algunas son
nuevas y relucientes, otras son viejas u oxidadas y
algunas otras están el medio. Incluso hay algunas de las que ¡no sabemos ni qué
es lo que hacen!
En lo relativo a módulos, esto puede llevar a nombres inexactos o inútiles
(¿alguien adivina qué hace el módulo `fudge`?), proyectos sin pruebas o
documentación, sin comentarios en el código fuente o funciones con nombres
incomprendibles.
Muchos módulos nisiquiera tienen mantenimiento constante. Si un módulo no tiene
una persona disponible respondiendo a preguntas y explicando qué hace el módulo
o, por lo menos, un rastro de documentación, éste módulo se vuelve un artefacto
alienígena bizarro, inusable e incomprensible para los *arqueolo-hackers* del
mañana.
Para aquellos módulos que si tienen documentación, ¿a qué nivel de calidad
podremos encontrarlos? Puede que sea una simple explicación de una línea:
`"ordena números por su valor en hexadecimal"`. Puede que sea un pedazo de
código fuente. Ambos casos son mejor que nada, pero suelen terminar (en el peor
de los casos) utiles sólo para los espeleólogos de módulos modernos: esos que
excavan el un código fuente para intentar entender cómo funciona realmente.
Escribir documentación excelente sirve para mantener a los usuarios *fuera* del
código fuente, proporcionando suficientes instrucciones para disfrutar de la
maravillosa abstracción que nos brinda el módulo.
Node.js tiene un "amplio" ecosistema: está compuesto por una larga lista de
módulos independientes que hacen una-cosa-bien y nada más. Existen
[excepciones](https://github.com/lodash/lodash), pero a pesar de estos feudos
menores, son los desarrolladores de módulos con un único propósito los que,
dada su superioridad numérica, verdaderamente mandan en el reino de Node.js.
Esta situación tiene una consecuencia natural: puede ser complicado encontrar
módulos de *calidad* que hagan exactamente lo que tú quieres que hagan.
**Esto está bien**. De verdad. Una exigencia de entrada menor y un problema
de detectabilidad son infinitamente mejor que un problema de cultura, donde
sólo unos pocos privilegiados puedan participar.
Además, la detectabilidad --como finalmente resulta-- va a ser más fácil de
solucionar.
## Todos los caminos llevan al README.md
La comunidad de Node.js ha respondido al reto de la detectabilidad de muchas
maneras diferentes.
Algunos desarrolladores con experiencia en Node.js se han asociado para crear
[listas curadas](https://github.com/sindresorhus/awesome-nodejs) de módulos de
calidad. Los desarrolladores aprovechan sus muchos años de examinar cientos
de módulos para compartir con los recién llegados la *crème de la crème*: los
mejores módulos de cada categoría. Además, esto podrá tomar forma de feeds RSS
o listas de correo de nuevos módulos que sean considerados útiles por miembros
confiables de la comunidad.
¿Qué hay de las redes sociales? Esta idea estimuló la creación de
[node-modules.com](http://node-modules.com/), un reemplazo de búsqueda para npm
que aprovecha tus conexiones sociales en GitHub para encontrar módulos que
gusten o hayan sido hechos por tus amigos.
Por supuesto también está la funcionalidad nativa de
[búsqueda](https://npmjs.org) de
npm: una opción segura y habitual punto de entrada para nuevos desarrolladores.
No importa cuál sea tu opción, no importa si los espeleólogos de módulos entran
al subsuelo de nuestros módulos por [npmjs.org](https://npmjs.org),
[github.com](https://github.com) o por cualquier otro sitio, estos usuarios
potenciales se encontrarán mirando fijamente a tu fichero README. Ya
que tus usuarios terminarán inevitablemente aquí, ¿qué podemos hacer para
potenciar al máximo su primera impresión?
## Espeleología de módulos profesional
### README: Tu única ventanilla
Un README es la primera -- y puede que única -- mirada que dedica un consumidor
de módulos a tu creación. El consumidor quiere que el módulo satisfaga su
necesidad, por lo tanto, debemos explicar exactamente qué necesidad satisface
el módulo y qué tan efectivo es.
Tu trabajo consiste en
1. decirles qué es (con contexto)
2. mostrarles cómo funciona
3. mostrarles cómo usarlo
4. decirles cualquier otro detalle relevante
Este es *tu* trabajo. Depende del creador del módulo probar que su trabajo es
una joya brillante en un mundo de módulos chapuceros. Ya que tu README será lo
primero que vean los ojos de muchos desarrolladores, la calidad de éste será
como se mida públicamente la calidad de tu trabajo.
### Sé breve
La falta de un README supone una bandera roja, aunque un README muy largo no es
indicativo de mucha calidad. El README ideal es tan corto como sea posible. La
documentación detallada es buena -- ¡haz páginas separadas para esto!
-- pero mantén tu README sucinto.
### Aprender del pasado
Suele decirse que, quién no aprende historia, está condenado a cometer los
mismos errores una y otra vez. Los desarrolladores han estado escribiendo
documentación desde hace bastantes años. Sería un desperdicio no mirar atrás
y fijarnos en lo que la gente ha estado haciendo bien antes de Node.js.
Perl, por todas las críticas que recibe, es en muchas maneras el abuelo
espiritual de Node. Ambos son lenguajes de alto nivel que adoptan muchas
expresiones de UNIX, son el combustible de gran parte de Internet y ambos
poseen un amplio ecosistema de módulos.
Al parecer, los denominados [monjes](http://perlmonks.org) de la comunidad
Perl tienen muchísima experiencia escribiendo
[REAMEs de calidad](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm).
CPAN es un recurso excelente al que vale la pena echar un ojo para aprender más
de una comunidad que escribe de manera consistente documentación de gran
calibre.
### ¿No hay README? No hay abstracción
No tener un README implica que los desarrolladores tengan que ahondar en tu
código para poder llegar a entenderlo.
Los Perl monks comparten cierta sabiduría acerca de este tema:
> Tu documentación estará completa cuando alguien sea capaz de usar tu módulo
sin tener que mirar el código fuente. Esto es muy importante. Esto hace posible
que puedas separar la interfaz documentada de la implementación interna (tripas)
de tu módulo. Esto es bueno, significa que eres libre de cambiar el código de
tu módulo mientras mantengas intacta la interfaz.
>
> Recuerda: la documentación y no el código define lo que hace un módulo.
-- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### Elementos clave
Una vez localizado el README, el valiente espeleólogo de módulos debe
escanearlo para discernir si se ajusta a las necesidades del desarrollo. Esencialmente,
esto se convierte en una serie de coincidencia de patrones que sus cerebros
deben resolver, donde cada paso les mete más dentro del módulo y sus detalles.
Digamos, por ejemplo, que mi búsqueda de un módulo de detección de colisiones
2D me lleva hasta
`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb) y
comenzamos a examinarlo de arriba a abajo:
1. *Nombre* -- los nombres auto-explicativos son los mejores.
`collide-2d-aabb-aabb` suena prometedor, aunque asumimos que se entiende lo que
significa "aabb". Si el nombre suena demasiado vago o sin relevancia, podría
ser una señal para evitar el módulo.
2. *Línea-única* -- tener una única línea que describa el módulo, resulta muy
útil para ofrecer una idea de lo que hace el módulo en algo más de detalle.
`collide-2d-aabb-aabb` dice esto:
> Determina si el movimiento de una caja delimitada alienada en un eje
(CDAE) colisiona
> con otras CDAE. (CDAE = AABB = axis-aligned bounding box)
Increíble. Define lo qué significa AABB y qué hace el módulo. Ahora queda
calibrar cómo de bien encajaría en mi código.
3. *Uso* -- En lugar de empezar a ahondar en la documentación de la API,
estaría genial si podemos ver el módulo en acción. Así podemos determinar
rápidamente si el código de ejemplo encaja con el estilo buscado y soluciona
el problema. La gente tiene muy diversas opiniones con cosas como las
promesas/callbacks y ES6. Si encaja a primera vista, entonces podemos
avanzar más y profundidad.
4. *API* -- el nombre, la descripción y el uso de este módulo son cosas muy
atractivas para mi. Muy probablemente estoy en un punto en el que voy a usar
este módulo. Sólo necesito revisar la API para asegurarme de que hace
exactamente lo que necesito y de que tendrá una integración sencilla con mi
código fuente. La sección de API debe detallar los objetos y funciones del
módulo, sus firmas, tipados de vuelta, callbacks y eventos. Debemos incluir el
tipado allá donde no sea obvio. Cualquier advertencia debe ser expuesta
muy claramente.
5. *Instalación* -- si he leído hasta aquí abajo, entonces estoy condenado a
instalar el módulo. Si existen notas no estándar de instalación, deberían ir
aquí, al igual que si es un simple `npm install`, también me gustaría verlo
mencionado aquí. Existen nuevos usuarios comenzando a usar Node.js todo el
tiempo, así que, enlazar a [npmjs.org](npmjs.org) con el comando de instalación
les facilita los recursos para descubrir cómo funciona el sistema de módulos de
Node.
6. *Licencia* -- la mayoría de los módulos ponen esto muy abajo, pero podría
ser mejor ponerlo más arriba; Es posible que excluyas rápidamente un módulo si
tiene una licencia incompatible con tu trabajo. Yo generalmente me mantengo en
licencias tipo MIT/BSD/X11/ISC. Si tienes una licencia no permisiva, colócala
muy arriba del módulo para prevenir cualquier tipo de confusión.
## Canalización cognitiva
El orden de lo expuesto anteriormente no ha sido escogido al azar.
Los consumidores de módulos usan muchos módulos y necesitan vontinuar
descubriendo muchos otros.
Cuando has visto cientos de módulox comienzas a descubrir que la mente se
beneficia de patrones predecibles.
También comienzas a construir tu propio sistema heurístico para aquella
información
que quieres y para esas banderas rojas que descalifican rápidamente algunos
módulos.
De esta forma, podemos deducir que un README deseable debe tener:
1. un formato predecible
2. ciertos elementos clave presentes
No necesitas usar *este* formato, pero intenta ser consistente para ahorrar a
tus usuarios valiosos ciclos cognitivos.
El orden presentado aquí se denomina cariñosamente "canalización cognitiva"
y podemos imaginarlo como un embudo en posición vertical, donde la zona más
ancha contiene los detalles pertinentes más generales y al movernos hacia abajo
en el embudo se presentan detalles más específicos, pertinentes únicamente para
un lector lo suficientemente interesado en nuestro trabajo como para para haber
llegado hasta las profundidades del documento.
Finalmente, el fondo podrá reservarse para detalles que incluyan un contexto
más profundo del trabajo (antecedentes, créditos, bibliografía, etc).
De nuevo, los monjes de Perl tienen sabiduría que comparten sobre esta materia:
> El nivel de detalle en la documentación de un módulo Perl generalmente va de
menos a más detalle. Tu sección de SIPNOSIS deberá contener un ejemplo de uso
mínimo (quizás algo tan simple como una única línea de código; evitar los casos
de uso poco comunes o cualquier cosa innecesaria para la mayoría de usuarios);
> la DESCRIPCIÓN debe describir tu módulo en términos más amplios, generalmente
con unos pocos párrafos; Se podrán dar más detalles de rutinas o métodos,
ejemplos de código más largos y otros materiales más a profundidad en secciones
posteriores.
>
> Idealmente, alguien ligeramente familiar con tu módulo debería ser capaz de
refrescar su memoria sin pulsar "avance página". A medida que el lector avance
por el documento, irá recibiendo progresivamente más cantidad de información.
>
> *-Tomado de `perlmodstyle`*
## Preocupación por el tiempo de los demás
Es Increíble, el orden de estos puntos clave debería decidirse por la rapidez
con la que alguien 'corto circuite' apuesta por tu módulo.
¿Suena poco prometedor? Piensa en esto: tu trabajo, cuando estás en ello con
un alto nivel de altruismo en mente, no se trata de "vender" a la gente tu
trabajo, se trata de permitir que evalúen qué hace tu creación lo más
objetivamente posible, que decidan si satisface sus necesidades o no -- además
de maximizar tu número de descargas y tu base de usuarios, por su puesto.
Este modo de pensar no se ajusta a todo el mundo; requiere dejar tu ego en la
puerta y dejar que el trabajo hable por si solo tanto como sea posible. Tu
único trabajo es describir lo que prometes tan sucintamente como te sea
posible, de manera que los espeleólogos de módulos puedan usar tu trabajo
cuando les encaje, o bien, encontrar otra opción que les encaje mejor.
## ¡Llamada a las armas!
¡Sal allí fuera, valiente constructor de módulos! ¡Haz que tu trabajo sea
visible y utilizable gracias a una documentación excelente!
## Bonus: otras buenas prácticas
Más allá de las claves de este artículo, existen otras técnicas que puedes
seguir (o evitar) para subir aún más la barra de calidad de tus README y
maximizar su usabilidad para el resto:
1. Considera incluir una sección de **Antecedentes** si tu módulo depende de
una importante pero no muy conocida abstracción o de otros ecosistemas. La
función de [`bisecting-between`](https://github.com/noffle/bisecting-between)
no es demasiado obvia si partimos de su nombre, por lo tanto, encontramos una
sección muy detallada de *Antecedentes* para definir y enlazar hacia grandes
conceptos y abstracciones que nadie tiene porqué entender para pilotar el
módulo. Este suele ser un buen lugar para explicar la motivación del módulo si
es que ya existen módulos similares en npm.
2. ¡Utiliza Links todo el tiempo! Si hablas de otros módulos, ideas o gente,
haz que ese texto de referencia se convierta en un enlace, de manera que los
visitante puedan comprender fácilmente tu módulo y las ideas en las que se
basa. Pocos módulos existen desde el vacío: todo el trabajo proviene de otro
trabajo, esto puede ayudar a tus usuarios a conocer la historia e inspiración
de tu módulo.
3. Incluye información acerca del tipado de los argumentos y de los parámetros
de salida (si éstos no son obvios). Priorizar las convenciones cuando sea
posible (`cb` probablemente se refiere a una función de callback, `num`
probablemente representa un `Number`, etc).
4. Incluye el código de ejemplo de la sección de **Uso** como un fichero más
del repositorio (algo como `example.js`). Está bastante bien tener código en
el README que los usuarios pueden ejecutar tras clonar el repositorio.
5. Utiliza los badges con cabeza. Es fácil
[abusar](https://github.com/angular/angular) de ellos. Pueden ser grande
fuentes de polémicas y debates interminables. Añaden ruido visual a tu README y
solo funcionan si el usuario está leyendo el README en un navegador conectado,
ya que, la mayoría de las imágenes están albergadas en un servidor de internet.
Para cada badget, es importante preguntarse: "¿Qué valor real aporta al
típico lector de este README?" ¿Tienes un badge de CI que muestre el
estado del build/test?
Estas señales deberían llegar a las partes interesadas mediante un email a
los mantenedores, o bien, creando automáticamente una incidencia -- siempre
hay que considerar qué audiencia quiere esta información en el README,
habría que preguntarse si existe algún flujo para que esta información
pueda llegar mejor hasta la audiencia deseada.
6. Formatear una API es altamente opinable. Utiliza el formato que tú
consideres más claro, pero asegúrate de que este formato contempla algunas
sutilezas:
a. Qué parámetros son opcionales y su valor por defecto
b. Información del tipado, allí donde no exista una convención obvia
c. Para los parámetros `opts` de un objeto, todas las claves y valores
aceptados
d. No húyas de proporcionar un pequeño ejemplo de uso de alguna función de
la API cuyo funcionamiento no sea obvio o no esté completamente cubierto en
la sección de *Uso*. Sin embargo, esto puede como una señal de complejidad
de la función, tal vez pudiera necesitar ser refactorizada, dividida en
funciones más pequeñas o eliminada en su conjunto.
e. ¡Utiliza links para los terminos especiales! En markdown se pueden
escribir
[notas al pie](https://daringfireball.net/projects/markdown/syntax#link) en
la parte de abajo del documento, hacer varias referencias al pie de página
resulta barato. Algunas de mis preferencias personales al formatear una API
pueden encontrarse
[aquí](https://github.com/noffle/common-readme/blob/master/api_formatting.md).
7. Si tu módulo está compuesto por una pequeña colección de funciones sin
estado, tener una sección de **Uso** similar a la de
[Node REPL session](https://github.com/noffle/bisecting-between#example) con
invocaciones a funciones y sus resultados puede comunicar el uso de manera más
clara que un fichero de código fuente en ejecución.
8. Si tu módulo proporciona un CLI (interfaz de comando) en lugar (o además) de
una API de programación, muestra invocaciones de comandos con ejemplos de uso,
así como la salida de éstos. Si creas o modificas un fichero, `cat` podrá
demostrar que ha cambiado antes y después.
9. No olvides utilizar las
[palabras clave](https://docs.npmjs.com/files/package.json#keywords) en tu
`package.json` para dirigir a los espeleólogos de módulos hasta el peldaño de
tu puerta.
10. Cuanto más cambies tu API, más trabajo necesitas hacer actualizando la
documentación -- esto implica que deberías mantener tus APIS pequeñas y
definidas con concreción desde las primeras fases.
Los requerimientos cambian a lo largo del tiempo, en lugar de cargar
supuestos directamente en la API de tus módulos, cárgalos en un nivel de
abstracción: el set del módulo mismo. Si los requerimientos *sí* cambian
y hacer-una-sola-cosa deja de tener sentido, entonces escribe un nuevo
módulo que haga aquello que necesitas ahora.
El módulo que 'hace-una-cosa-concreta' permanece como un modelo válido y
valioso en el ecosistema de npm, tu corrección en caliente implicará
únicamente la sustitución de un módulo por otro.
11. Finalmente, recuerda por favor que tu sistema de control de versiones y su
fichero README integrado sobrevivirán a tu
[servicio del repositorio](https://github.com) y a cualquiera de las cosas a
las que enlaces -- especialmente a imágenes -- así que -- incluye -- todo lo
esencial para que futuros usuarios puedan usar tu trabajo.
## Bonus: *common-readme*
No es una coincidencia que este formato sea utilizado por
[**common-readme**](https://github.com/noffle/common-readme), un conjunto de
guías para READMEs además de un práctico generador en línea de comandos. Si te
gusta lo que está escrito aquí, ahorrarás algo de tiempo escribiendo READMEs
con `common-readme`. También encontrarás ejemplos reales de módulos con este
formato.
También puede interesarte
[standard-readme](https://github.com/richardlitt/standard-readme), una versión
más estructurada y formateada para un escribir los READMEs.
## Bonus: Ejemplares
La teoría está muy bien, pero, ¿cómo es un fichero excelente de README? Aquí
tenemos algunos que encarnan muy bien los principios de este artículo:
- [https://github.com/noffle/ice-box](https://github.com/noffle/ice-box)
- [https://github.com/substack/quote-stream](https://github.com/substack/quote-stream)
- [https://github.com/feross/bittorrent-dht](https://github.com/feross/bittorrent-dht)
- [https://github.com/mikolalysenko/box-intersect](https://github.com/mikolalysenko/box-intersect)
- [https://github.com/freeman-lab/pixel-grid](https://github.com/freeman-lab/pixel-grid)
- [https://github.com/mafintosh/torrent-stream](https://github.com/mafintosh/torrent-stream)
- [https://github.com/pull-stream/pull-stream](https://github.com/pull-stream/pull-stream)
- [https://github.com/substack/tape](https://github.com/substack/tape)
- [https://github.com/yoshuawuyts/vmd](https://github.com/yoshuawuyts/vmd)
¿Conoces alguno otro buen ejemplo? [Envía un pull request](https://github.com/noffle/art-of-readme/pulls)!
## Bonus: Lista de verificación para un LÉEME
A continuación, una lista de comprobación para medir la calidad de tu fichero
README:
- [ ] Una línea explicando el propósito del módulo
- [ ] Contexto de fondo necesario y enlaces
- [ ] Enlaces a fuentes informativas de términos potencialmente desconocidos
- [ ] Ejemplo de uso *ejecutable* y claro
- [ ] Instrucciones de instalación
- [ ] Documentación extensa de la API
- [ ] Realización de [tunelización cognitiva](https://github.com/noffle/art-of-readme#cognitive-funneling)
- [ ] Mencionar excepciones y limitaciones por adelantado
- [ ] No usar imágenes para mostrar información crítica
- [ ] Licencia
## Autor
Soy [noffle](http://blog.eight45.net/about/). Se me conoce por mi
[blog](http://blog.eight45.net), [tweet](https://twitter.com/noffle) y
[hack](https://github.com/noffle).
Este pequeño proyecto comenzó en mayo en la conferencia squatconf de Berlín,
mientras investigaba cómo los _Perl monks_ hacían documentación y lamentaba el
estado actual de los README en el ecosistema de Node. Esto me sirvió como
estimulante para crear
[common-readme](https://github.com/noffle/common-readme). La sección "README
Tips" está repleta de consejos, por lo que decidí recogerlos todos en un
artículo sobre escribir READMEs. ¡Así nació Art of README!
## Otras lecturas
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## Notas al pie
1. <a name="footnote-1"></a>Gracias,
[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)!
2. <a name="footnote-2"></a>Consultar [The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html). Sin embargo la mayoría
de sistemas actuales, no ordenan las mayúsculas antes que los caracteres en
minúsculas reduciendo así la utilidad de la convención de usar todo mayúsculas
a una simple representación llamativa.
## Créditos
Un sentido agradecimiento a [@mafintosh](https://github.com/mafintosh) y a
[@feross](https://github.com/feross) por el ánimo recibido que necesité para
despegar esta idea y empezar a escribir.
Gracias a los lectores increíbles que aparecen a continuación por encontrar
errores y enviarme sus PRs :heart::
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
¡Gracias a [@qihaiyan](https://github.com/qihaiyan) por traducir Art of
README a chino! Los siguientes usuarios también contribuyeron:
- [@BrettDong](https://github.com/brettdong) (por revisar la puntuación en la
versión china)
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
¡Gracias a [@lennonjesus](https://github.com/lennonjesus) por traducir Art of
README a portugués brasileño! Los siguientes usuarios también contribuyeron a
este artículo:
- [@rectius](https://github.com/rectius)
¡Gracias a [@jabiinfante](https://github.com/jabiinfante) por traducir Art of
README a español!
¡Gracias a [@Ryuno-Ki](https://github.com/Ryuno-Ki) por traducir Art of
README a alemán! Los siguientes usuarios también contribuyeron a este artículo:
- [@randomC0der](https://github.com/randomC0der)
¡Gracias a [@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro) y
[@Ruben Madelaine](https://github.com/Ruben-Madelaine)
por traducir Art of README a Francés!
Para terminar, ¡gracias por todo el feedback! Por favor hacer vuestros
comentarios [como una _issue_](https://github.com/noffle/art-of-readme/issues)!
## ¡Pull requests bienvenidas!
¿Has encontrado un error? ¿Algo no tiene sentido? ¡Enviar un [pull
request](https://github.com/noffle/art-of-readme/pulls)! Por favor evitar
enviar cambios de estilo --
Seguramente no serán aceptados. ¡Gracias!
## Licencia
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/).
================================================
FILE: README-fr.md
================================================
# L'art du README
*Cet article a été traduit à partir de la version [Anglaise](README.md)
et est également disponible en [Chinois](README-zh.md),
[Portugais](README-pt-BR.md), [Espagnole](README-es-ES.md) et [Allemand](README-de-DE.md).*
## Etymologie
D'où vient le terme «README»?
La nomenclature remonte au moins aux années 1970 [et le
PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html),
bien que cela puisse même remonter à l'époque des notes informatives en papier placées au sommet
de piles de cartes perforées, avec "READ ME!" ("LISEZ-MOI!") griffonné sur eux, décrivant leur utilisation.
Un lecteur<sup>[1](#footnote-1)</sup> suggéra que le titre README puisse être un petit coup de pouce ludique
en hommage au très fameux roman, de Lewis Carroll, intitulé Les *Aventures d'Alice au pays des merveilles*,
comprennant une potion et un gâteau étiquetés respectivement avec "DRINK ME" (BUVEZ-MOI) et "EAT ME" (MANGEZ-MOI).
Le modèle de README apparaissant en majuscules est un point récurrent tout au long de l'histoire.
En plus du carractère visuellement frappant de l'utilisation des majuscules, les systèmes UNIX
triaient les majuscules avant les minuscules, mettant commodément le README
avant le reste du contenu du répertoire<sup>[2](#footnote-2)</sup>.
L'intention est claire: *"Il s'agit d'informations importantes que l'utilisateur doit lire avant
de poursuivre".* Explorons ensemble ce qui constitue une information "importante" dans
ces temps modernes.
## Pour les créateurs, pour les consommateurs
Cet article traite des READMEs. Il présente ce qu'ils font, pourquoi ils sont
absolument nécessaires, et comment bien les construire.
Cet article peut intéresser les créateurs de modules car, en tant que constructeurs
de modules, leur travail consiste à créer des éléments durables et compréhensibles.
C'est une motivation inhérente, même si l'auteur n'a pas l'intention
de partager son travail.
En effet, même si développé pour une utilisation privée,
une fois six mois passés, un module sans documentation
devient inconnu même aux yeux de son créateur.
Cet article est également pour les consommateurs de modules, puisque chaque
auteur de module en consomme également. Node.js a un degré d'interdépendance
très sain : personne n'est aux pieds de l'arborescence des dépendances.
Bien qu'il se concentre sur Node.js, l'auteur soutient que ses leçons s'appliquent
aussi bien à d’autres écosystèmes de programmation.
## De nombreux modules: certains bons, d'autres mauvais
L'écosystème Node.js est alimenté par ses modules. [npm](https://npmjs.org) est
la magie qui fait tout cela *tourner*. Au cours d'une semaine, les développeurs Node évaluent
des dizaines de modules à intégrer dans leurs projets. C'est beaucoup de puissance
que de pouvoir tirr quotidiennement, autant de modules, aussi vite que l'on puisse
écrire `npm install`.
Comme tout écosystème extrêmement accessible, la barre de qualité varie. npm
fait de son mieux pour bien empaqueter tous ces modules et les expédier ici et
là en fonction du besoin. Cependant, les modules récupérés sont très variés:
certains sont neufs et brillants, d'autres sont cassés et rouillés,
et d'autres encore sont situés quelque part entre les deux.
Il y en a même certains dont nous ne savons tout simplement pas ce qu'ils font!
Pour les modules, cela peut prendre la forme de noms inexacts ou inutiles
(une idée sur ce que fait le module `fudge`?), pas de documentation, pas de tests,
pas de commentaires dans le code source ou des noms de fonctions incompréhensibles.
Beaucoup n'ont pas de mainteneur actif. Si un module n'a aucune personne disponible pour
répondre aux questions et expliquer ce que fait un module, combiné à une absence de documentation
laissé en héritage, un module devient un artefact extraterrestre bizarre, inutilisable
et incompréhensible par les archéologues-hackers de demain.
Pour les modules ayant de la documentation, où se situent-ils en terme de qualité?
C'est peut-être juste une description à une seule ligne: `"trie les nombres par leur valeure hexadécimal"`,
ou il s'agirait d'un exemple extrait du code. C'est déjà mieux que rien, mais ils ont
tendance à finir, dans le pire des cas, comme module pour les spéléologues des temps modernes:
fouillant dans le code source pour essayer de comprendre comment il fonctionne réellement.
Ecrire une excellente documentation, c'est garder les utilisateurs
*hors* du code source en fournissant des instructions suffisantes pour profiter des
merveilleuses abstractions que votre module apporte.
Node.js a un écosystème "large": il est en grande partie constitué d'une très longue liste de
modules indépendants, adeptes du faire-une-chose-mais-le-faire-bien. Il y a des
[exceptions](https://github.com/lodash/lodash), mais malgré ces fiefs mineurs,
ce sont les modules à "but unique" qui, étant donné leur plus grand nombre, gouvernent réellement le
Royaume de Node.js.
Cette situation a une conséquence naturelle: il peut être difficile de trouver des modules *de qualité*
qui font exactement ce que vous voulez.
**C'est ok**. Vraiment. Une barre basse à l'entrée et un problème de découvrabilité est
infiniment mieux qu'un problème de culture, où seuls quelques privilégiés peuvent participer.
De plus, la découvrabilité - en fait - est plus facile à gérer.
## Tous les chemins mènent au README.md
La communauté de Node.js a répondu au défi de la découverte de
différentes manières.
Certains développeurs expérimentés de Node.js se sont associés pour créer
des [listes organisées](https://github.com/sindresorhus/awesome-nodejs)
de modules de qualité. Les développeurs tirent parti de leurs nombreuses
années à examiner des centaines de modules différents en partageant avec
les nouveaux arrivants la crème de la crème :
les meilleurs modules de chaque catégorie. Cela peut également prendre la
forme de flux RSS et de listes de diffusion de nouveaux modules jugés utiles
par les membres de confiance de la communauté.
Qu'en est-il du graphe social ? Cette idée a stimulé la création de
[node-modules.com](http://node-modules.com/), un remplacement de recherche
npm qui exploite votre graphe social GitHub pour trouver des modules que
vos amis aiment ou ont créés.
Bien sûr, il existe également la fonctionnalité de [recherche](https://npmjs.org)
intégrée de npm: une valeur sûre par défaut et le point d'entrée habituel pour tous
les nouveaux développeurs.
Quelle que soit votre approche, peu importe si un spéléologue de module entre
dans les profonds souterrains de modules sur [npmjs.org](https://npmjs.org),
[github.com](https://github.com) ou ailleurs, cet utilisateur
potentiel finira par regarder votre README en face. Étant donné que vos
utilisateurs se retrouveront inévitablement ici, que peut-on faire pour rendre
leurs premières impressions efficaces au maximum ?
## Spéléologues de module professionnel
### Le README: votre point d'entrée
Le README est le premier - et peut-être le seul - document qu'un consommateur de module examinera
lors de la découverte de votre création. Le consommateur souhaite qu'un module réponde à son besoin,
vous devez donc expliquer exactement ce que votre module permet de faire et avec quelle efficacité il le fait.
Votre travail consiste à:
1. leur dire ce que c'est (avec un contexte)
2. leur montrer à quoi il ressemble en action
3. leur montrer comment l'utiliser
4. leur indiquer tout autre détail pertinent
C'est *votre* travail. C'est au créateur du module de prouver que son travail est un
joyau brillant dans la mer des modules abandonnés. Puisque tant de développeurs
trouverons leur chemin vers votre README avant d'intier toute autre action, la qualité
du README sera comme une mesure de votre travail face au public.
### Brièveté
L'absence d'un README est un puissant drapeau rouge, mais un long README n'est pas
non plus gage de qualité. Le README idéal est aussi court que possible,
sans l'être trop. La documentation détaillée est bonne - séparez
les pages pour cela! - mais gardez votre README succinct.
### Apprendre du passé
On dit que ceux qui n'étudient pas leur histoire sont condamnés à refaire les mêmes
erreurs à nouveau. Les développeurs écrivent de la documentation depuis un certain nombre
d'années. Ce serait un gaspillage de ne pas regarder un peu en arrière et voir ce que les gens
faisaient juste avant Node.js.
Perl, malgré toutes les critiques qu'il reçoit, est à certains égards le grand-père spirituel
de Node.js. Les deux sont des langages de script de haut niveau, adoptent de nombreux idiomes UNIX,
sont utilisés dans une grande partie d'Internet, et disposent d'un vaste écosystème de modules.
Il s'avère que les [moines](http://perlmonks.org) de la communauté Perl ont en effet une grande expérience
en rédaction de [README de qualité](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm). CPAN est une
merveilleuse ressource qui vaut la peine d'être lue pour en savoir plus sur une communauté
qui a rédigé des documentations de bonne facture.
### Pas de README? Pas d'abstraction
Pas de README signifie que les développeurs devront fouiller dans votre code pour
le comprendre.
Les moines Perl ont une sagesse à partager à ce sujet:
> Votre documentation est complète lorsque quelqu'un peut utiliser votre module sans jamais
> avoir à regarder son code. C'est très important. Cela vous permet de séparer l'interface
> documentée de votre module de son implémentation interne (tripes). C'est bien car cela
> signifie que vous êtes libre de modifier les composants internes du module autant que
> que vous le voulez, pour peu que l'interface l'interface reste la même.
>
> N'oubliez pas: la documentation, pas le code, définit ce que fait un module.
> -- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### Éléments clé
Une fois qu'un README est identifié, le chercheur de module doit le scanner afin de confirmer si
celui-ci répond bien à ses besoins de développement. Cela devient essentiellement une série de validation
de critères d'acceptation que leur cerveau doit résoudre, où chaque étape les plonge de plus en plus
dans le module et ses détails.
Disons, par exemple, que ma recherche d'un module de détection de collision 2D m'amène
à [`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb). je
commence à l'examiner de haut en bas:
1. *Nom* - les noms explicites sont les meilleurs. Le nom `collide-2d-aabb-aabb`
semble prometteur, bien que cela suppose que je sache ce qu'est un "aabb".
Si le nom semble trop vague ou sans rapport, cela peut être un signal pour passer à autre chose.
2. *One-liner* - avoir un one-liner qui décrit le module est utile pour
avoir une idée de ce que fait le module avec un peu plus de détails.
`collide-2d-aabb-aabb` l'exprime très bien
> Détermine si un cadre de délimitation aligné sur l'axe mobile (AABB) entre en collision avec
> un autres AABB.
Génial: il définit ce qu'est un AABB et ce que fait le module. Maintenant pour évaluer comment
cela s'intégrerait dans mon code:
3. *Utilisation* - plutôt que de commencer à fouiller dans la documentation de l'API, ce serait génial de
voir à quoi ressemble le module en action. Je peux rapidement déterminer si l'exemple
correspond au style et au problème souhaités. Les gens ont beaucoup d'opinions
sur des choses comme les promesses/callbacks et ES6. Si cela correspond à la demande, alors je
peut continuer vers plus de détails sur le fonctionnement.
4. *API* - le nom, la description et l'utilisation de ce module semblent tous attrayants pour moi.
Je suis très susceptible d'utiliser ce module à ce stade. J'ai juste besoin de scanner
l'API pour m'assurer qu'elle fait exactement ce dont j'ai besoin et qu'elle s'intègre
facilement dans ma base de code. La section API doit détailler les objets du module
et fonctions, leurs signatures, types de retour, rappels et événements dans le détail.
Les types doivent être inclus là où ils ne sont pas évidents. Les mises en garde devraient être
clairement explicités.
5. *Installation* - si j'ai lu jusque-là, je suis convaincu d'au moins essayer le
module. S'il y a des notes d'installation non standard, voici où elles iraient,
mais même si c'est juste une simple commande d'`installation npm`, j'aimerais voir cela mentionné,
aussi. De nouveaux utilisateurs commencent à utiliser Node.js tout le temps, donc avoir un lien vers npmjs.org
et la commande d'installation associée, leur fournit toutes les ressources nécessaires pour
comprendre comment les modules Node.js fonctionnent.
6. *Licence* - la plupart des modules placent cela tout en bas, mais cela pourrait
en fait être placé plus haut; vous êtes susceptible d'exclure un module TRÈS
rapidement s'il possède une licence incompatible avec votre travail. Je m'en tiens généralement aux
dérivés des licences MIT / BSD / X11 / ISC. Si vous avez une licence non permissive, placez-la
tout en haut du module pour éviter toute confusion.
## Progressivité cognitive
L'ordre des éléments ci-dessus n'a pas été choisi au hasard.
Les consommateurs de modules utilisent et analysent de nombreux modules.
Une fois que vous avez regardé des centaines de modules, vous commencez à remarquer que l'esprit
bénéficie de modèles prévisibles.
Vous commencez également à élaborer votre propre heuristique personnelle pour les informations que vous
veulez, et quels drapeaux rouges disqualifient rapidement les modules.
Ainsi, il s'ensuit que dans un README, il est souhaitable d'avoir:
1. un format prévisible
2. certains éléments clés présents
Vous n'avez pas besoin d'utiliser *ce* format, mais essayez d'être cohérent pour éviter la perte de
précieux cycles cognitifs à vos utilisateurs.
La recommandation présentée ici est appelée «progressivité cognitive»,
et peut être imagée en un entonnoir, tenu debout, où l'extrémité la plus large contient
les détails les plus généraux et les plus pertinents, et la descente progressive dans l'entonnoir présente
des détails de plus en plus spécifiques, n'étant pertinents que pour un lecteur suffisamment intéressé
par le module pour avoir atteint ce niveau de profondeur.
Finalement, la fin peut être réservée pour les détails sur le contexte
de la crétaion (background, crédits, biblio, etc.).
Une fois de plus, les moines Perl ont une sagesse à partager sur le sujet:
> Le niveau de détail dans la documentation du module Perl va généralement du
> moins détaillé au plus détaillé. Votre section SYNOPSIS devrait
> contenir un exemple minimal d'utilisation (peut-être aussi court qu'une simple ligne de
> code; sautez les cas d'utilisation inhabituels et tout ce qui n'est pas nécessaire pour
> la plupart des utilisateurs); la DESCRIPTION doit décrire votre module en termes généraux,
> généralement en quelques paragraphes; le rests des détails sur le module,
> ses méthodes, ses longs exemples ou autres doivent être donné dans les sections suivantes.
>
> Idéalement, quelqu'un qui connaît un peu votre module devrait être
> capables de se rafraîchir la mémoire sans pour autant devoir pacourir l'entièreté de votre
> docuement. Au cours de sa lecture, votre lecteur devrait recevoir, graduellement,
> des connaissances de plus en plus poussées.
> -- de `perlmodstyle`
## Se soucier du temps des gens
Impressionnant; l'ordre de ces éléments clés doit être décidé en fonction de la rapidité
avec laquelle ils permettent à quelqu'un de «court-circuiter» et abandonner votre module.
Cela semble sombre, n'est-ce pas? Mais pensez-y: votre travail, quand vous le faites
avec un altruisme optimal à l'esprit, ce n'est pas pour «vendre» votre travail à des gens.
C'est de les laisser évaluer ce que votre création fait, aussi objectivement que possible, et
de décider si celui-ci réponde ou non à leurs besoins - ne pas, par exemple, maximiser vos
téléchargements ou votre base d'utilisateur.
Cet état d'esprit ne plaît pas à tout le monde; Cela implique qu'il faille laisser son ego à
l'netrée et laisser l'œuvre parler d'elle-même autant que possible. Votre seul travail est
de décrire sa promesse aussi succinctement que possible, afin que les spéléologues de modules puissent
soit utilisez votre travail quand c'est un ajustement, soit passez à autre chose.
## Appel aux armes!
Allez de l'avant, courageux dénicheurs de module, et rendez votre travail compréhensible et utilisable
par tous, grâce à une excellente documentation!
## Bonus: autres bonnes pratiques
En dehors des points clés de l'article, il existe d'autres pratiques que vous pouvez
suivre (ou ne pas suivre) pour élever encore plus la barre de qualité de votre README et
maximiser son utilité pour les autres:
1. Pensez à inclure une section **Contexte** si votre module dépend
d'autres abstractions importantes mais peu connues ou d'autres écosystèmes. La fonction
de [`bissecting-between`](https://github.com/noffle/bisecting-between) n'est pas
immédiatement évident à partir de son nom, il a donc une section détaillée *Contexte*
pour définir et établir un lien avec les grands concepts et abstractions dont on a besoin
pour comprendre et utiliser votre module. C'est aussi un excellent endroit pour expliquer
la motivation du module si des modules similaires existent déjà sur npm.
2. Référencez agressivement! Si vous parlez d'autres modules, idées ou personnes, utilisez
une référence afin que les visiteurs puissent plus facilement analyser votre module
et les idées sur lesquelles il s'appuie. Peu de modules existent à partir de rien: tout le travail vient
d'autres travaux, il est donc avantageux d'aider les utilisateurs à suivre l'historique de votre module et
ses inspirations.
3. Incluez des informations sur les types d'arguments et renvoyez les paramètres si ce n'est pas le cas
évident. Préférez la convention dans la mesure du possible (`cb` signifie probablement un rappel
fonction, `num` signifie probablement un `nombre`, etc.).
4. Incluez l'exemple de code dans **Usage** en tant que fichier dans votre dépôt - peut-être comme
`exemple.js`. C'est formidable d'avoir un code README que les utilisateurs peuvent exécuter si
ils clonent le référentiel.
5. Soyez judicieux dans votre utilisation des badges. Ils sont faciles à
[abuser](https://github.com/angular/angular). Ils ajoutent du bruit visuel à votre
README et ne fonctionne généralement que si l'utilisateur lit votre Markdown dans un
navigateur web, car les images sont souvent hébergées ailleurs sur Internet.
Pour chaque badge, considérez: "quelle valeur réelle apporte ce badge
au lecteur type de ce README?" Avez-vous un badge CI pour afficher la version / le test
statut? Ce signal permettrait de mieux atteindre les parties importantes en envoyant un email
aux mainteneurs ou en créant automatiquement une github issue. Considérez toujours les
destinataires des données présentes dans votre README et demandez-vous s'il existe un flux dédié
pour ces données qui pourrait mieux atteindre le public ciblé.
6. Le formatage de l'API est hautement adaptable. Utilisez le format que vous pensez
le plus clair, mais assurez-vous que votre format exprime des subtilités importantes:
a. quels paramètres sont facultatifs et leurs valeurs par défaut
b. informations de typage, là où elles ne ressortent pas de la convention
c. pour les paramètres d'objet `opts`, toutes les clés et valeurs acceptées
d. n'hésitez pas à fournir un petit exemple d'utilisation d'une fonction API si
ce n'est pas évident ou entièrement couvert dans la section **Utilisation**.
Cependant, cela peut également être un signal fort que la fonction est trop complexe
et doit être remaniée, divisée en fonctions plus petites ou supprimée
tout simplement
e. liez agressivement la terminologie spécialisée! En Markdown, vous pouvez garder des
[notes de bas de page](https://daringfireball.net/projects/markdown/syntax#link) en
bas de votre document, donc y mettre les détails des points annexes devient tout simplement
bon marché. Certaines de mes préférences personnelles sur le formatage de l'API peuvent être
trouvé [ici](https://github.com/noffle/common-readme/blob/master/api_formatting.md)
7. Si votre module est une petite collection de fonctions sans état, ayant un
**Section d'utilisation** en tant que [Node REPL
session](https://github.com/noffle/bisecting-between#example) de la fonction
les appels et les résultats peuvent communiquer l'utilisation plus clairement qu'un code source
fichier à exécuter.
8. Si votre module fournit une CLI (interface de ligne de commande) au lieu (ou en plus)
d'une API programmatique, affichez des exemples d'utilisation sous forme d'appels de commandes
ainsi que leur retour. Si vous créez ou modifiez un fichier, utilisez la commande `cat`
pour mettre en évidence le changement avant et après.
9. N'oubliez pas d'utiliser `package.json`
[mots-clés](https://docs.npmjs.com/files/package.json#keywords) pour diriger
les chercheurs de module jusqu'à votre porte.
10. Plus vous modifiez votre API, plus vous devez effectuer de mise à jour
de la documentation - l'implication ici est que vous devez conserver vos API
petite et concrètement définie dès le début. Les exigences changent avec le temps, mais
au lieu d'hypothèses de chargement frontal dans les API de vos modules, chargez
les remonter d'un niveau d'abstraction: le module s'est posé. Si les exigences
*faire* changer et 'faire-une-chose-concrète' n'a plus de sens, alors tout simplement
écrivez un nouveau module qui fait ce dont vous avez besoin. Le 'faire-une-chose-concrète'
module reste un modèle valide et précieux pour l'écosystème npm, et votre
la correction de cap ne vous coûte rien d'autre qu'une simple substitution d'un module pour
un autre.
11. Enfin, n'oubliez pas que votre référentiel de contrôle de version et ses
Le fichier README intégré survivra à votre [hôte du référentiel](https://github.com) et
tout élément vers lequel vous créez un lien hypertexte - en particulier les images - donc *en ligne* n'importe quoi
c'est essentiel pour les futurs utilisateurs qui gambadent votre travail.
## Bonus: *common-readme*
Ce n'est pas par hasard, c'est aussi le format utilisé par
[**common-readme**](https://github.com/noffle/common-readme), un ensemble de README
directives et générateur de ligne de commande pratique. Si vous aimez ce qui est écrit ici,
vous pouvez gagner du temps en écrivant des README avec `common-readme`. Vous trouverez
de vrais exemples de modules avec ce format également.
Vous pouvez également profiter du
[standard-readme](https://github.com/richardlitt/standard-readme), qui est une
version plus structurée et formatable du format README commun.
## Bonus: exemplaires
La théorie est bonne, mais à quoi ressemblent les excellents README? En voilà quelques-uns
qui, je pense, incarnent bien les principes de cet article:
- https://github.com/noffle/ice-box
- https://github.com/substack/quote-stream
- https://github.com/feross/bittorrent-dht
- https://github.com/mikolalysenko/box-intersect
- https://github.com/freeman-lab/pixel-grid
- https://github.com/mafintosh/torrent-stream
- https://github.com/pull-stream/pull-stream
- https://github.com/substack/tape
- https://github.com/yoshuawuyts/vmd
## Bonus: la liste de validation d'un README
Une liste de contrôle utile pour évaluer la progression de votre README:
- [ ] Une seule ligne expliquant le but du module
- [ ] Contexte et liens nécessaires
- [ ] Des termes potentiellement inconnus renvoient à des sources d'information
- [ ] Exemple d'utilisation clair, *exécutable*
- [ ] Instructions d'installation
- [ ] Documentation complète de l'API
- [ ] Applique la [progressivité cognitive](https://github.com/noffle/art-of-readme#cognitive-funneling)
- [ ] Mises en garde et limitations mentionnées à l'avance
- [ ] Ne se fie pas aux images pour fournir des informations capitales
- [ ] Licence
## L'auteur
Je suis [noffle](http://blog.eight45.net/about/). Je suis connu pour mes divers
[blogs](http://blog.eight45.net), [tweets](https://twitter.com/noffle) et
[hacks](https://github.com/noffle).
Ce petit projet a commencé en mai à Berlin chez squatconf, où je creusais
la façon dont les moines Perl écrivaient leur documentation, tout en déplorant
l'état des READMEs dans l'écosystème Node.js. Cela m'a alorsincité à créer
[common-readme](https://github.com/noffle/common-readme). Cependant, la section
pour les "Conseils README" débordant de conseils, je me suis alors dit que
cela pourrait être utilement de les collecter dans un article dédié à la rédaction de README.
Ainsi, n'aissait l'Art of README!
Vous pouvez me joindre à `noffle@eight45.net` ou sur Freenode IRC dans `#eight45`.
## Lectures complémentaires
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## Notes de bas de page
1. <a name="footnote-1"> </a> Merci,
[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)!
2. <a name="footnote-2"> </a> Voir [The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html).
Cependant, la plupart des systèmes actuels ne trieront pas les majuscules avant toutes les minuscules,
réduisant ainsi l'utilité de cette convention à son seul visuel frappant.
## Crédits
Un grand merci à [@mafintosh](https://github.com/mafintosh) et
[@feross](https://github.com/feross) pour les encouragements dont j'avais bien besoin afin
de faire décoller cette idée et commencer à écrire!
Merci aux super lecteurs suivants d'avoir remarqué des erreurs et de m'avoir envoyé
des PRs :coeur: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
Merci à [@qihaiyan](https://github.com/qihaiyan) d'avoir traduit l'Art of
README en chinois! Les utilisateurs suivants ont également fait des contributions:
- [@BrettDong](https://github.com/brettdong) pour la révision de la ponctuation en version chinoise.
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
Merci à [@lennonjesus](https://github.com/lennonjesus) d'avoir traduit l'Art
of README en portugais brésilien! Les utilisateurs suivants ont également fait des contributions:
- [@rectius](https://github.com/rectius)
Merci à [@jabiinfante](https://github.com/jabiinfante) pour la traduction de l'Art
of README en espagnol!
Merci à [@Ryuno-Ki](https://github.com/Ryuno-Ki) pour avoir traduit l'Art of
README en allemand! Les utilisateurs suivants ont également fait des contributions:
- [@randomC0der](https://github.com/randomC0der)
Merci à [@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro) et
[@Ruben Madelaine](https://github.com/Ruben-Madelaine)
pour la traduction de l'Art of README en français!
Enfin, merci pour tous les commentaires! Veuillez partager vos commentaires [en tant qu'issue](https://github.com/noffle/art-of-readme/issues)!
## Les contributions sont les bienvenues!
Vous avez repéré une erreur? Quelque chose n'a pas de sens? Envoyez-moi une [pull
request](https://github.com/noffle/art-of-readme/pulls)!
Veuillez cependant éviter de faire des changements stylistiques s'il-vous-plait,
il est peu probable qu'ils soient acceptés. Merci!
## Licence
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
================================================
FILE: README-ja-JP.md
================================================
# Art of README
## 語源
”README”の語源は何でしょうか？
この命名は、 _少なくとも_ 1970 年代の[PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html)まで遡りますが、もしかしたらパンチカードの束の上に「READ ME!」と書かれた紙のメモを置いて、使い方を説明していた時代まで遡るかもしれません。
読者の方<sup>[1](#footnote-1)</sup>から、README はルイス・キャロルの _不思議の国のアリス_ に登場する _"DRINK ME"_ と書かれた飲み薬や _"EAT ME"_ と書かれたケーキを意識しているのでは、とも指摘していただきました。
README は歴史的にすべて大文字で表記されてきました。すべて大文字を使用することで、視覚的なインパクトがあることに加え、UNIX システムは小文字の前に大文字をソートするので、ディレクトリ内の他のコンテンツ<sup>[2](#footnote-2)</sup>より README を優先させることができます。
その意図は明確で、_"この情報はユーザーが先に進む前に読むべき重要な情報です"_ ということです。ではこの現代において、”重要な情報”とは何なのか一緒に探ってみましょう。
## 製作者向けかつユーザー向け
本記事は README についての記事です。README が何をするのか、なぜ絶対に必要なのか、そしてどのようにうまく作るのかについて書かれています。
本記事はモジュールの製作者向けに書かれたものです。モジュールの製作者の仕事は、長く使えるものを作ることです。これは、たとえ製作者が自分の作品を共有するつもりがないとしても、内発的な動機でしょう。6 ヶ月も経つと、ドキュメントのないモジュールは、製作者にも見慣れないものに見えてきます。
本記事はまた、モジュールのユーザー向けにも書かれています。すべてのモジュール製作者は、モジュールのユーザーでもあります。Node は非常に健全な相互依存性を持っており、依存関係ツリーの最下部には、ひとつもモジュールはありません。
ここでは Node に焦点を当てていますが、筆者はその教訓は他のプログラミング言語のエコシステムにも応用できると考えています。
## 玉石混交のたくさんのモジュール
Node のエコシステムは、モジュールによって支えられています。[npm](https://npmjs.org)は、それを実現するための魔法です。Node 開発者は彼らのプロジェクトに含まれる何十ものモジュールを短い間に評価します。`npm install`とさえ書ければ、日々の業務に有益なモジュールを引っ張ってこれるのは、すごいことです。
アクセスしやすいエコシステムでは良くあることですが、モジュールの品質にはばらつきがあります。npm はモジュールをすべてきれいに梱包して広く届けるために最善を尽くしています。しかし、発見できるツールは多種多様で、ピカピカで新しいものもあれば、壊れて錆びついたものもあり、またその中間のものもあります。中には、何をするものなのか分からないものまであります！
モジュールで言えば、不正確な名前や役に立たない名前（`fudge`モジュールが何をするかわかりますか？）、ドキュメントがないもの、テストがないもの、ソースコードコメントがないもの、理解し難い関数名を持つものなどがあります。
多くのケースでは、アクティブなメンテナはいません。もしモジュールの質問に答えたりモジュールの機能を説明したりできる人がいなければ、ドキュメントがないことと相まって、モジュールはエイリアンのアーティファクトとなり、使い物にならず理解もできないものになるでしょう。
ドキュメントがあるモジュールの場合、その品質はどれくらいのもでしょうか？`"16進数で数値をソートする"`という 1 行の説明だけかもしれません。あるいは、サンプルコードのスニペットだけかもしれません。どちらも何もないケースと比べれば進歩と言えますが、現代のモジュールユーザーに、実際にどのように動作するのかを理解するためにソースコードを掘り下げるという最悪のシナリオをもたらすこともあります。優れたドキュメントを書くことは、あなたのモジュールを十分に抽象化する説明を行うことで、ユーザーをソースコードから _遠ざける_ ことなのです。
Node は”広大な”エコシステムで、ひとつのことに特化し、互いに独立した、非常にたくさんのモジュールで構成されています。[例外](https://github.com/lodash/lodash)はありますが、こうした小さな領地はあっても、1 点に特化した市民たちが、その数の多さから Node 王国を真に支配しています。
このような状況では当然の帰結ですが、欲しいものを正確に実現する _質の高い_ モジュールを見つけるのは難しいでしょう。
**これで問題ありません**。本当に。参入のハードルの低さと検索性の低さという問題は、一部の特権階級しか参加できない文化の問題よりも、非常に良いことです。
加えて、検索性の低さは、結果的に、対処しやすいものです。
## すべての道は README.md に通ず
Node コミュニティは様々な方法で検索性の低さに対応してきました。
ベテランの Node 開発者が結束して良質なモジュールの[キュレーションリスト](https://github.com/sindresorhus/awesome-nodejs)を作成しました。開発者たちは長年にわたって何百ものモジュールを調査し、それぞれのカテゴリーで最高のモジュールを Node の初心者のために公開しています。これはまた、信頼できるコミュニティメンバーによって、有用だとみなされた新しいモジュールの RSS フィードやメーリングリストの形式をとることもあるかもしれません。
ソーシャルグラフというアイデアは[node-modules.com](http://node-modules.com/)の作成に拍車をかけました。この npm 検索代替ツールはあなたの GitHub のソーシャルグラフを活用して、あなたの友人が好きなモジュールや作成したモジュールを見つけることができるのです。
もちろん、npm 備え付きの[検索機能](https://npmjs.org)もあります。安全で一般的な選択肢であり、新しい開発者のためにいつも開かれています。
どのようなアプローチをとろうとも、モジュールユーザーが[npmjs.org](https://npmjs.org)や[github.com](https://github.com)などで検索しても、ユーザーは最終的にはあなたの README と正面から向き合うことになるわけです。ユーザーは必然的にここにたどり着くわけですから、彼らの第一印象を最大限に良くするために何ができるでしょうか？
## プロフェッショナルなモジュール探索
### README: ワンストップショップ
README は、モジュールのユーザーにとって、最初の、そしておそらく唯一の、あなたのモジュールに関する情報です。ユーザーは自分のニーズを満たすモジュールを求めているので、あなたは自身のモジュールがどのようなニーズを満たし、どのように効果的にニーズを満たすかを正確に説明する必要があります。
あなたの仕事は
1. 文脈を含めて、モジュールが何であるかを伝える
2. 実際にどのように見えるかを見せる
3. 使い方を紹介する
4. その他の関連する内容を伝える
これが _あなたの_ 仕事です。自分の作品が粗悪なモジュールの海の中で輝く宝石であることを証明するのは、モジュール作成者次第です。多くの開発者の目は、何よりも先に README に向くので、README の品質があなたの作品の評価基準になるのです。
### 簡潔さ
README がないのは大きな危険信号ですが、README の長さが品質の高さを示すというものではありません。理想的な README はこれ以上短くならないほどに短いものです。詳細なドキュメントは別のページにして、README は簡潔にしましょう。
### 過去に学ぶ
歴史を学ばない者は、同じ過ちを繰り返すと言われます。開発者がドキュメントを書くようになってから、かなりの年月が経ちました。Node が登場する前に、人々が何をしていたのか少し振り返ってみる価値はあるでしょう。
Perl は、否定されることもありますが、ある意味では Node の精神的な祖父母にあたります。どちらも高水準のスクリプト言語で、多くの UNIX イディオムを採用し、インターネットの発展を牽引し、モジュールの広範なエコシステムを備えていることを特徴としています。
Perl コミュニティの[monks](http://perlmonks.org)たちは、[質の高い README](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm)を書くことにかけては実に多くの経験を積んでいることで知られています。CPAN は、質の高い水準のドキュメントを書いたコミュニティについてもっと学ぶための素晴らしいリソースです。
### README がなければ抽象化できない
README がなければ、ユーザーはモジュールを理解するためにコードを掘り下げる必要があります。
この問題に関しては、Perl monks は知恵を共有してくれています:
> ユーザーがコードを見ることなく、あなたのモジュールを使用できていれば、あなたのドキュメントは完璧だということです。これは非常に重要です。ドキュメントが完璧であれば、モジュールの文書化されたインターフェース部分と内部実装（心臓部）を分離することが可能になります。これは、インターフェースが同じである限り、モジュール内部を自由に変更できることを意味するので、良いことです。
>
> モジュールが何をするのかを定義するのは、コードではなく、ドキュメントであることを覚えておいてください。
> -- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### 重要な要素
README があれば、モジュールユーザーはそれを読んで自身のニーズに合致しているかどうかを確かめなければなりません。これは本質的には、開発者の脳内で解かれる一連のパターンマッチング問題となり、一歩ずつモジュールの詳細について深く掘り下げていきます。
たとえば、2D 衝突検出モジュールを探していて、[`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb)に辿り着いたとします。私は、このモジュールを上から下まで調べ始めました:
1. _名前_ -- 自明の名前がベスト。`collide-2d-aabb-aabb`は期待できそうですが、これは私が”aabb”が何かを知っていることを前提としています。もし名前があまりにも漠然としていたり無関係に思えたら、他のモジュールに移るかもしれません。
2. _ワンライナー_ -- モジュールを説明するワンライナーを持っていると、モジュールが何をするのか少しだけ詳しく知りたい時に便利です。`collide-2d-aabb-aabb`は、
> Determines whether a moving axis-aligned bounding box (AABB) collides with other AABBs.
素晴らしい。AABB とは何か、モジュールが何をするか定義しています。では、どれくらい私のコードにうまく組み込めるでしょうか:
3. _使い方_ -- API ドキュメントを掘り下げ始めるよりも、モジュールが実際にどのように見えるかを確認するのは良いアイデアです。サンプルの JS が求めているスタイルや解決したい問題にマッチしているかどうか判断できるからです。Promise やコールバックや ES6 といったものに対して、多くの人が異なる意見を持っていることでしょう。もし、要求を満たしてくれるなら、私はさらに詳細に進むことができます。
4. _API_ -- このモジュールの名前、説明、そして使い方すべて魅力的に思えます。ここまでで、私にとってはこのモジュールを使う可能性が非常に高いです。API をざっと見て、私が必要とすることを正確に行い、私のコードベースに正確に組み入れることが可能であることを確認する必要があります。API のセクションは、そのモジュールのオブジェクトと関数、シグネチャ、戻り値の型、コールバック、イベントなどを詳しく説明する必要があります。型が明らかでない場合は、それも含めるべきです。注意書きも明確にすべきでしょう。
5. _インストール方法_ -- ここまで読んだら、このモジュールを使ってみようという気になります。もし標準的でないインストール方法があればここに書くべきですが、通常の`npm install`であったとしても、それについての言及が欲しいところです。npmjs.org へのリンクとインストールコマンドを書いてあげることで、Node の新しいユーザー は、Node モジュールがどのように動作するのかの理解することができます。
6. _ライセンス_ -- ほとんどのモジュールはこれを一番下に置いていますが、実はもっと上にあったほうが良いかもしれません。あなたの仕事に不適切なライセンスを持つモジュールは、なるべく早くに排除したいでしょう。私は一般に MIT/BSD/X11/ISC 風のライセンスにこだわります。もしパーミッシブライセンスではないライセンスなら、混乱を避けるために一番上に貼り付けてください。
## コグニティブ・ファネリング
上記の順序は何もランダムに選んだわけではありません。
モジュールのユーザーはたくさんのモジュールを使用し、そして多くのモジュールを調べる必要があります。
何百ものモジュールを見ていると、予測可能なパターンに対して精神的な安定感を感じ始めます。
また、どのような情報が欲しいのか、どのような危険信号があればモジュールは不適合だと素早く判断できるのか、自分なりのヒューリスティックを構築し始めるのです。
したがって、README には次のようなものがあることが望ましいと言えます:
1. 予測可能なフォーマットであること
2. 特定の重要な要素が存在すること
必ずしも _上記の_ フォーマットを使う必要はありませんが、ユーザーの貴重な認知サイクルの無駄を省くために、一貫性を保たせるようにしましょう。
ここで紹介する順序は、”コグニティブ・ファネリング”と呼ばれ、漏斗を直立したイメージで、最も広い端には、最も一般的な情報が含まれています。漏斗の奥に進むほど、より具体的になり、あなたの作品に興味を持ち、その奥に到達した読者だけに適切な詳細があります。最後に、一番下には、作品のより深い文脈（背景、クレジット、参考文献など）に興味を持った人たちだけのために、そうした詳細を表示することができます。
今回もまた、Perl monks がこのテーマについて知恵を共有してくれています:
> Perl モジュールのドキュメントは一般的にあまり詳細でないものから、より詳細なものまであります。SYNOPSIS セクションには最小限の使用例（おそらく 1 行程度のコードで、例外やほとんどのユーザーが必要としないものは省略してください。）を記載し、DESCRIPTION には大まかに、通常は数段落でモジュールについて記述し、モジュールのルーチンやメソッドの詳細、長めのコード例、その他の深い内容については以降のセクションで説明すべきです。
>
> 理想としては、あなたのモジュールについて少し知っている人が、”page down”キーを押すことなく、記憶を更新できるようにすることです。読者がこのドキュメントを読み進めるにつれて、徐々に多くの知識を得ることができるはずです。
> -- `perlmodstyle` より
## 人の時間に配慮する
素晴らしいことに、上記の重要な要素の順番は、誰かが「ショート」して、どれだけ早くモジュールを放棄させるかによって決定されています。
暗い話に聞こえますよね。でも考えてみてください。利他主義を念頭においた場合、あなたの仕事は、あなたの作品を「売り込む」こと（たとえばダウンロード数やユーザー数を最大化させること）ではありません。あなたの作品が何をするものなのかできる限り客観的に評価させ、それが彼らのニーズを満たしているかどうかを判断してもらうことです。
この考え方は、万人に受けるものではありません。自身のエゴは抑えて、作品になるべく語らせる必要があります。あなたの唯一の仕事は、その作品の約束事をできるだけ簡潔に説明することです。そうすれば、モジュールのユーザーはあなたの作品がニーズにマッチした時に使用するか、あるいは他の作品を探すかすることができます。
## 要請！
さあ、勇敢なるモジュール探索者よ、優れたドキュメントによって、あなたの作品を発見しやすく、使いやすくしてください。
## おまけ: その他のグッドプラクティス
本記事のキーポイントの他にも、README の品質の水準をぐっと高め、他の人にとっての有用性を最大化するために、従うことができる（あるいは従わなくても良い）プラクティスが存在します。
1. あなたのモジュールが、重要だがあまり知られていない抽象概念や他のエコシステムに依存している場合、**背景**セクションを記載することを検討しましょう。[`bisecting-between`](https://github.com/noffle/bisecting-between)の関数は、その名前からすぐに分かるようなものではないので、詳細な _背景_ セクションを設けて、それを使って理解するために必要な大きな概念や抽象概念を定義しリンクしています。また、同様のモジュールがすでに npm に存在する場合、このモジュールを制作した動機を説明するのにも最適な場所です。
2. 積極的なリンク化！他のモジュール、アイデア、人について話す場合は、訪問者がより簡単にあなたのモジュールとモジュールのもとになったアイデアを理解できるように、リファレンスをリンクにしましょう。他の何にも依存しないモジュールはほとんどありません。すべてモジュールは他のモジュールに由来します。ユーザーがあなたのモジュールの歴史とインスピレーションをたどるのを助けることは、とても大切なことなのです。
3. 引数や戻り値のパラメータが明確でない場合は、その情報を含めること。可能な限り慣例に従うこと（`cb`はコールバック関数、`num`は`Number`を意味する、など）
4. **使い方**にあるサンプルコードを、リポジトリのファイルとして含めること -- 例: `example.js`。ユーザーがリポジトリをクローンしたときに、README に記載されているコードを実際に実行できるならば、それは素晴らしいことです。
5. バッジの使用には慎重を期してください。[濫用](https://github.com/angular/angular)される恐れがあります。また、些細な議論や終わりのない議論の温床になる可能性もあります。バッジは README の視覚的なノイズになることに加え、一般的にユーザーがオンラインのブラウザであなたのマークダウンファイルを読んでいる場合にのみ機能します。画像はほとんどがインターネット上のどこかでホストされているからです。それぞれのバッジについて考慮してみましょう: ”このバッジは README の一般的な読者に、どのような価値を提供しているのだろうか？”。ビルド/テストのステータスを表示する CI バッジはありますか？このステータスは、メンテナにメールを送ったり自動的に Issue を作成したりするほうが、重要な関係者は気付きやすいはずです。README に記載されている情報の読者のことを常に考え、その情報が意図した読者にもっとよく届くようなフローを作れないか自問しましょう。
6. API のフォーマットは、些細な議論の的になり得ます。最も分かりやすいと思われるフォーマットを使ってください。ただし、そのフォーマットが重要な細部を記述できていることを確認してください。
a. どのパラメータが任意なのか、そしてそのデフォルト値
b. 慣例から明らかでない場合の型情報
c. `opts`オブジェクトパラメータがある場合、受け取るすべてのキーと値
d. API の関数の使い方が明白でない、あるいは**使い方**セクションで完全にカバーできていない場合は、小さなサンプルであっても提供することをためらわないこと。ただし、これはその関数が複雑すぎるというしるしでもあり、リファクタリングやより小さな関数への分割、あるいは完全に削除する必要があるということでもあります。
e. 専門用語は積極的にリンク化する！マークダウンファイルでは、[脚注](https://daringfireball.net/projects/markdown/syntax#link)をドキュメントの一番下に記載しておくと、ドキュメント中で何度でも参照しやすくなります。API のフォーマットに関する私の個人的な好みについては、[こちら](https://github.com/noffle/common-readme/blob/master/api_formatting.md)を参照してください。
7. モジュールがステートレス関数の小さなコレクションである場合、関数の呼び出しと結果の[Node の REPL セッション](https://github.com/noffle/bisecting-between#example)として**使い方**セクションを記載すれば、実行可能なソースコードファイルよりも分かりやすく使い方を伝えることができるかもしれません。
8. モジュールがプログラム的な API の代わりに（あるいはそれに加えて）CLI（コマンドラインインターフェース）を提供しているなら、コマンドの呼び出しとその結果として、使用例を示してください。ファイルを作成または変更するようならば、`cat`コマンドで変更前と変更後の状態を示しましょう。
9. モジュールを探している人に見つけてもらうために、`package.json`の[キーワード](https://docs.npmjs.com/files/package.json#keywords)を使うことを忘れないでください。
10. API を変更すればするほど、ドキュメントの更新に労力を割かなければならなくなります。つまり、早い段階で、API を小さく、具体的に定義しておくべきだということです。要件は時間とともに変化するものですが、モジュールの API を事前に想定するのではなく、モジュールセットという、一段上の抽象化されたレイヤーを作りましょう。もし要件が変わって「特定のことをする」だけでなくなったら、必要なことをする新しいモジュールを書けば良いのです。「特定のことをする」モジュールは、npm エコシステムにとって有効かつ貴重なモデルであり続け、軌道修正する際には、あるモジュールを別のモジュールに置き換えるという単純な作業以外には何もコストはかかりません。
11. 最後に、バージョン管理されているリポジトリとその中の README は、[リポジトリのホスト](https://github.com)やハイパーリンク先（特に画像）よりも長く存続することは覚えておいてください。そのため、将来のユーザーがあなたの作品を理解するために不可欠なものは、すべて埋め込んでおくようにしてください。
## おまけ: _common-readme_
偶然ではありませんが、これは[**common-readme**](https://github.com/noffle/common-readme)という README のガイドラインと便利なコマンドラインジェネレータでも使われている形式です。もしこの記事に書かれていることが気に入ったら、`common-readme`を使えば README を書く時間を節約できるかもしれません。この形式を使っている実際のモジュールの例も紹介されています。
また、[standard-readme](https://github.com/richardlitt/standard-readme)もおすすめです。こちらはより構造化されていて、リント可能な一般的な README フォーマットです。
## おまけ: 実例
理論は良いとして、優れた README というものは具体的にどのようなものでしょうか？ここでは、私がこの記事の原則をよく体現していると思うものをいくつか紹介します:
- https://github.com/noffle/ice-box
- https://github.com/substack/quote-stream
- https://github.com/feross/bittorrent-dht
- https://github.com/mikolalysenko/box-intersect
- https://github.com/freeman-lab/pixel-grid
- https://github.com/mafintosh/torrent-stream
- https://github.com/pull-stream/pull-stream
- https://github.com/substack/tape
- https://github.com/yoshuawuyts/vmd
## おまけ: README チェックリスト
README の完成度を測るのに便利なチェックリスト:
- [ ] モジュールの目的を説明するワンライナー
- [ ] 必要な背景情報やリンク
- [ ] 見慣れない用語の、有益なリソースへのリンク
- [ ] 明確かつ _実行可能な_ 使用例
- [ ] インストール方法
- [ ] 豊富な API ドキュメント
- [ ] [コグニティブ・ファネリング](https://github.com/noffle/art-of-readme#cognitive-funneling)の適用
- [ ] 注意点・制限事項の事前説明
- [ ] 重要な情報の説明を画像に頼らない
- [ ] ライセンス
## 著者
著者は[noffle](http://blog.eight45.net/about/)です。[blog](http://blog.eight45.net)、[tweet](https://twitter.com/noffle)、[hack](https://github.com/noffle)などで知られています。
この小さなプロジェクトは、5 月にベルリンの squatconf で始まりました。そこで私は Perl monks がどのようにドキュメントを書いているかを掘り下げていて、また Node エコシステムの README の状況を嘆いていました。これが[common-readme](https://github.com/noffle/common-readme)を作る動機になりました。"README Tips"セクションは、ヒントであふれるほどだったので、README の書き方について記事にまとめると役に立つと判断しました。こうして、Art of README が誕生したのです！
私の連絡先は、`noffle@eight45.net`または Freenode IRC の`#eight45`です。
## 関連資料
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## 脚注
1. <a name="footnote-1"></a>ありがとう、
[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)！
2. <a name="footnote-2"></a>[The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html)を参照してください。しかし、現在のほとんどのシステムでは、大文字を小文字の前にソートすることはないため、この慣習の有用性は大文字の視覚的なインパクトだけにとどまります。
## クレジット
このアイデアを実現させ、書き始めるために必要な励ましをくれた[@mafintosh](https://github.com/mafintosh)と[@feross](https://github.com/feross)に心からの感謝を！
間違いに気付いて PR を送ってくれた以下の素晴らしい読者に感謝します :heart: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
Art of README を中国語に翻訳してくださった[@qihaiyan](https://github.com/qihaiyan)に感謝します！また下記のユーザーにも貢献していただきました:
- [@BrettDong](https://github.com/brettdong) 中国語版の句読点の修正について
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
Art of README をブラジルのポルトガル語に翻訳してくださった[@lennonjesus](https://github.com/lennonjesus)に感謝します！また下記のユーザーにも貢献していただきました:
- [@rectius](https://github.com/rectius)
Art of README をスペイン語に翻訳してくださった[@jabiinfante](https://github.com/jabiinfante)に感謝します！
Art of README をドイツ語に翻訳してくださった[@Ryuno-Ki](https://github.com/Ryuno-Ki)に感謝します！また下記のユーザーにも貢献していただきました:
- [@randomC0der](https://github.com/randomC0der)
Art of README をフランス語に翻訳してくださった[@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro)と[@Ruben Madelaine](https://github.com/Ruben-Madelaine)に感謝します！
最後に、たくさんの感想をありがとうございます！意見があれば[Issue](https://github.com/noffle/art-of-readme/issues)に共有してください。
## ライセンス
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
================================================
FILE: README-pt-BR.md
================================================
# Art of README
*Este artigo foi traduzido do [Inglês](README.md) e traduzido para [Chinês](README-zh.md),
[Português](README-pt-BR.md), [Espanhol](README-es-ES.md), [Alemão](README-de-DE.md)
e [Francês](README-fr.md).*
## Etimologia
De onde vem o termo "README"?
A nomenclatura data de *pelo menos* 1970
[e do PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html),
embora possa ainda remeter de volta aos dias das notas de papel colocadas no topo
da pilha de cartões perfurados, com um "READ ME!" rabiscado sobre eles,
descrevendo a sua utilização.
Um leitor<sup>[1](#footnote-1)</sup> sugeriu que o título README possa ser uma
referência a Alice no País das Maravilhas, de Lewis Carroll, onde existe uma
poção e um bolo escrito *"DRINK ME"* (ME BEBA) e *"EATME"* (ME COMA)
respectivamente.
O padrão README aparecendo todo em maiúsculo é uma característica consistente
ao longo da história. Além do impacto visual de usar tudo em caps, sistemas
UNIX ordenam letras maiúsculas antes de minúsculas, colocando convenientemente
o README antes de todo o resto do conteúdo do diretório<sup>[2](#footnote-2)</sup>.
A intenção é clara: *"esta é uma informação importante para o usuário ler antes
de prosseguir"*. Vamos explorar juntos o que constitui uma "informação importante" na
era moderna.
## Para os criadores, para os consumidores
Este é um artigo sobre os READMEs. Sobre o que eles fazem, por que são absolutamente
necessários, e como escrevê-los direito.
É escrito para os criadores de módulos, pois, como um construtor de módulos,
seu trabalho é criar algo que vá durar. Esta é uma motivação inerente, mesmo se
o autor não tiver a intenção de compartilhar seu trabalho. Depois de passados 6
meses, um módulo sem documentação começa a virar algo novo e desconhecido.
Também é escrito para os consumidores de módulo, pois cada autor de módulo é
também um consumidor. Node tem um grau bastante saudável de interdependência:
ninguém vive na parte inferior da árvore de dependência.
Apesar de ser focado em Node, o autor afirma que as suas lições se aplicam
também a outros ecossistemas de programação.
## Muitos módulos: alguns bons, alguns ruins
O ecossistema Node é alimentado por seus módulos. [NPM](https://npmjs.org) é a
mágica que faz com que tudo *aconteça*. No decorrer de uma semana, programadores
Node avaliam dezenas de módulos para inclusão em seus projetos. Esta é uma grande
quantidade de energia agitada diariamente, madura para a colheita, tão rápida
quanto alguém possa escrever `npm install`.
Assim como qualquer ecossistema que é extremamente acessível, o grau de qualidade
varia. npm faz o seu melhor para organizar bem todos os módulos e entregá-los da
melhor forma possível. Entretanto, as ferramentas achadas lá variam bastante:
algumas são novas e brilhantes. Outras são velhas e enferrujadas. E algumas estão
ali no meio termo. Há também aquelas que sequer temos idéia do que fazem!
Para módulos, isto pode tomar a forma de nomes incorretos ou inúteis (alguém
adivinha o que o módulo `fudge` faz?), sem documentação, sem testes, nenhum
comentário de código-fonte, ou nomes de função incompreensíveis.
Muitos não têm um mantenedor ativo. Se um módulo tem nenhuma pessoa disponível
para responder às perguntas e explicar o que ele faz, combinado com nenhum ou
restos de documentação deixados para trás, torna-se um artefato alienígena
bizarro, inutilizável e incompreensível pelos hackers arqueólogos de amanhã.
Para aqueles módulos que não têm documentação, onde estariam seu espectro de
qualidade? Talvez eles sejam descritos com apenas uma linha: `"ordenar números
pelo valor hexadecimal"`. Talvez seja um trecho de código de exemplo. Estas são
duas melhorias sem valor, mas elas tendem a resultar no pior cenário para um
moderno caçador de tesouros: cavar o código-fonte para tentar entender como ele
realmente funciona. Escrever uma documentação excelente é sobre como manter os
usuários *fora* do código-fonte, fornecendo instruções suficientes para
aproveitar as abstrações maravilhosas que seu módulo traz.
Node tem um ecossistema "amplo": é em grande parte composto de uma lista muito
longa de módulos independentes do tipo faça-alguma-coisa-bem, sob nenhuma bandeira
que não a sua própria. Existem [exceções](https://github.com/lodash/lodash),
mas apesar destes poucos feudos, são os plebeus de uma única causa quem, devido
ao seu grande número, verdadeiramente governam o reino do Node.
Isso tem uma consequência natural: pode ser difícil encontrar módulos de qualidade
que façam exatamente o que você precisa.
**Tudo bem com isso**. De verdade. A falta de barreiras para entrar e um problema
para encontrar as coisas é infinitamente melhor do que um problema de cultura,
onde apenas uns poucos privilegiados podem participar.
Além disso, descoberta -- como se vê -- é mais fácil de tratar.
## Todos os caminhos levam ao README.txt
A comunidade Node tem respondido ao desafio da descoberta de diferentes formas.
Alguns desenvolvedores Node experientes se unem para criar
[listas revisadas](https://github.com/sindresorhus/awesome-nodejs) de módulos de
qualidade.
Os desenvolvedores unem o conhecimento de seus muitos anos examinando centenas de
módulos diferentes para compartilhar com os recém-chegados a *Crème de la Crème*:
os melhores módulos em cada categoria.
Isso também pode assumir a forma de feeds RSS e listas de discussão de novos
módulos considerados dignos e úteis por membros confiáveis da comunidade.
Sobre o Social Graph? Essa ideia estimulou a criação do
[node-modules.com](http://node-modules.com/), um substituto para a busca npm que
usa o lado social do seu Github para encontrar módulos que seus amigos gostam ou
criaram.
Claro que também existe a funcionalidade de [busca](https://npmjs.org) nativa do
npm: um padrão seguro e porta de entrada comum a novos desenvolvedores.
Não importa a sua abordagem, independentemente de o consumidor encontrar seu módulo
no [npmjs.org](https://npmjs.org), no [Github.com](https://github.com) ou em
algum outro lugar, eles vão estar olhando o seu README na frente. De forma que
seus usuários irão fatalmente acabar aqui, o que pode ser feito para fazer esta
breve impressão ser o mais eficaz possível?
## Caçador de tesouros profissional
### O README: Your one-stop shop
Um README é a entrada principal - e talvez a única - para um consumidor olhar
para o sua criação. O consumidor quer um módulo para atender sua necessidade,
então você deve explicar exatamente o que seu módulo faz, e como efetivamente
ele faz isso.
Seu trabalho é:
1. dizer o que isso é (dentro de um contexto)
2. mostrar como é em ação
3. mostrar como utilizar
4. mostrar outros detalhes relevantes
Este é *seu* trabalho. Cabe ao criador do módulo provar que seu trabalho é uma
pedra preciosa brilhando em meio a um mar de módulos. Considerando que muitos
desenvolvedores irão encontrar o caminho para o seu README antes de mais nada,
a qualidade aqui é a vitrine do seu trabalho voltado para o público.
### Brevidade
A falta de um README é uma bandeira vermelha poderosa, mas mesmo um README longo
não é necessariamente garantia de alta qualidade. O README ideal é tão curto
quanto é possível ser, sem ser curto demais. A documentação detalhada é boa -
faça páginas separadas para ela! - Mas mantenha o seu README breve.
### Aprenda com o passado
Diz-se que aqueles que não estudam a história estão condenados a cometer os mesmos
erros novamente. Os desenvolvedores têm escrito documentação por alguns anos.
Seria um desperdício não olhar um pouco para trás e ver o que as pessoas fizeram
antes do Node.
Perl, para todos as críticas que recebe, é de certa forma o avô espiritual do Node.
Ambas são linguagens de script de alto nível, adotam muitas expressões idiomáticas
do UNIX, combustível de grande parte da internet, e ambos apresentam um grande
ecossistema de módulos.
É por isso que os [monges](http://perlmonks.org) da comunidade Perl tem grande
experiência em escrever
[READMEs de qualidade](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm).
CPAN é um recurso maravilhoso que vale a pena a leitura afim de aprender mais
sobre uma comunidade que escreveu consistentemente documentação de alto calibre.
### Sem README? Sem abstração
A falta de um README significa que os desenvolvedores terão que mergulhar no seu
código para entendê-lo.
Os Monges do Perl tem uma sabedoria para compartilhar sobre isso:
> Sua documentação está completa quando alguém consegue utilizar seu módulo sem
> nunca precisar olhar o seu código. Isso é muito importante. Isso torna possível
> que você separe a interface documentada do seu módulo da implementação interna
> (entranhas). Isso é bom porque significa que você está livre para mudar as
> entranhas do seu módulo enquanto a interface continua a mesma.
Lembre-se: a documentação, não o código, define o que um módulo faz.
-- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### Elementos chave
Uma vez loacalizado um README, o bravo caçador de tesouros deve avaliar se o
módulo atende às necessidades do desenvolvimento. Isto se torna essencialmente
uma série de padrão de problemas de harmonização para o seu cérebro para resolver,
onde cada passo leva mais a fundo no módulo e seus detalhes.
Digamos, por exemplo, que minha busca por um sistema de detecção de colisões em
2D me leve ao
[`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb). Eu
começo a examina-lo de cima a baixo:
1. *Nome* -- Nomes autoexplicativos são os melhores. `collide-2d-aabb-aabb` soa
promissor, embora assuma que eu saiba o que um "aabb" é. Se o nome soa muito
vago ou sem relação com nada, pode ser um sinal para abandonar.
2. *Uma linha* -- Ter um linha descrevendo o módulo é útil para ter uma ideai do
que o módulo faz em mais detalhes.
`collide-2d-aabb-aabb` diz isso:
> Determina se um axis-aligned-bounding-box (AABB) em movimento colide com
> outros AABBs.
Implessionante: isso define o que um AABB é e o que o módulo faz. Agora, para
medir o quão bem ele irá se adequar em meu código:
3. *Utilização* -- ao invés de começar a mergulhar na documentação da API, seria
ótimo ver o que o módulo faz em ação. Eu posso rapidamente determinar se um
exemplo JS se encaixa no estilo desejado e resolve o problema. As pessoas têm
muitas opiniões em coisas como promisses/callbacks e ES6. Se isso acontecer
caber a conta, então eu posso proceder a uma maior detalhe. If it does fit the
bill, then I can proceed to greater detail.
4. *API* -- o nome, descrição e utilização deste módulo chamam minha atenção.
Estou muito propenso a usar este módulo neste momento. Eu só preciso varrer a
API para me certificar de que ele faz exatamente o que eu preciso e que será
fácil de integrar em minha base de código. A seção API deveria detalhar objetos
e funções do módulo, suas assinaturas, tipos de retorno, callbacks e eventos
em bom nível de detalhe. Tipos devem ser incluídos onde eles não são óbvios.
Ressalvas devem ser claras.
5. *Instalação* -- se li até aqui embaixo, então eu estou decidido a experimentar
o módulo. Se houver notas de instalação fora do padrão, aqui é onde eles vão,
mas mesmo se for apenas um `inpm nstall` comum eu gostaria de saber isso também.
Novos usuários começam a usar o Node todo o tempo, assim, ter um link para
[npmjs.org](http://npmjs.org) e um comando de instalação lhes dá os recursos
para descobrir como os módulos Node funcionam.
6. *Licença* -- a maioria dos módulos colocam isso na parte inferior, mas, na
verdade, seria melhor ter mais acima. É provável que você decida muito
rapidamente não usar um módulo se ele tiver uma licença incompatível com o seu
trabalho. Eu geralmente uso os sabores MIT / BSD / X11 / ISC. Se você tiver
uma licença não-permissiva, coloque-a no topo do módulo para evitar qualquer
confusão.
## Afunilamento cognitivo
A ordenação acima não foi escolhida ao acaso.
Consumidores de módulos usam muitos módulos e precisam avaliar muitos módulos.
Uma vez que você olha centenas de módulos você começa a perceber que a mente se
beneficia de padrões previsíveis.
Você começa a desenvolver sua própria heurística sobre qual informação você quer
e quais as bandeiras vermelhas desqualificam um módulo rapidamente.
Assim, segue o que um bom README deve desejavelmente ter:
1. um formato previsível
2. a presença de alguns elementos-chave
Você não precisa usar *este* formato, mas tente ser consistente para poupar
tempo de processamento precioso do cérebro de seus usuários
A ordenação aqui apresentada é carinhosamente chamada de "afunilamento cognitivo",
e pode ser imaginada como um funil em posição vertical, em que a extremidade
mais larga contém os mais amplos detalhes pertinentes, e movendo-se mais
profundamente para dentro do funil, detalhes mais específicos que são pertinentes
apenas para um leitor que está suficientemente interessado em seu trabalho para
ter chegado tão a fundo no documento. Finalmente, a parte inferior pode ser
reservada para detalhes que somente aqueles intrigados com o mais profundo
contexto do trabalho (background, créditos, bibliografia, ...)
Mais uma vez, os monges Perl tem sabedoria para compartilhar sobre o assunto:
> O nível de detalhe de documentação de um módulo Perl geralmente vai de
> menos detalhada a mais detalhada. Sua seção SINOPSE deve conter um exemplo de
> utilização mínima (talvez tão pouco como uma única linha de código; ignorar os
> casos de uso incomuns ou qualquer coisa que não seja necessária para a maioria
> dos usuários); A descrição deve descrever o seu módulo em termos gerais,
> geralmente em apenas alguns parágrafos; mais detalhes do módulo de rotinas ou
> métodos, exemplos de códigos longos, ou outro material mais aprofundado deve ser
> dado nas secções subsequentes.
>
> O ideal é que alguém que é um pouco familiarizado com o seu módulo deve ser
> capaz de refrescar a sua memória sem chegar ao "fim da página". A medida que seu
> leitor continue a ler o documento, deve receber uma
> quantidade cada vez maior de conhecimento. -- de `perlmodstyle`
## Preocupe-se com o tempo das pessoas
Awesome; the ordering of these key elements should be decided by how quickly
they let someone 'short circuit' and bail on your module.
Isso soa sombrio, não é? Mas pense nisso: seu trabalho, quando você o está fazendo
com o altruísmo ideal em mente, não é "vender" as pessoas no seu trabalho. É
deixá-las avaliar o que sua criação faz o mais objetivamente possível, e decidir
se ela atende às suas necessidades ou não. Não para, digamos, maximizar seus
downloads ou base de usuários.
Essa mentalidade não é para todos; ela exige botar seu ego de lado e deixar o
trabalho falar por si, tanto quanto possível. Seu único trabalho é para descrever
sua promessa da forma mais sucinta possível, de modo caçadores de módulos podem
querer usar o seu trabalho quando lhes servir, ou buscar outro que sirva.
## Mãos à obra
Vá em frente, bravo desbravador de módulos, e faça o seu trabalho de descoberta
e utilização através de documentação de qualidade!
## Bônus: outras boas práticas
Fora dos pontos-chave do artigo, há outras práticas a seguir (ou não) para
aumentar o nível de qualidade do seu README ainda mais e maximizar a sua utilidade
para os outros.
1. Considere a inclusão de uma seção **Background** se o seu módulo depender de
importantes mas não muito conhecidas abstrações ou outros ecosistemas. A
função de [`bisecting-between`](https://github.com/noffle/bisecting-between)
não é imediatamente óbvia a partir de seu nome, por isso tem uma detalhada
seção *Background* para definir e referenciar os grandes conceitos e abstrações
que é preciso entender para utiliza-lo. Este também é um ótimo lugar para
explicar a motivação do módulo, se módulos semelhantes já existirem no NPM.
2. Referencie agressivamente! Se você falar sobre outros módulos, idéias ou
pessoas, faça com que o texto referência um link para que os visitantes possam
entender mais facilmente o seu módulo e as ideias em que ele se baseia. Existem
alguns módulos em um vácuo: todo o trabalho vem de outros trabalhos, isso ajuda
os usuários a seguir a história e inspiração do seu módulo.
3. Inclua a informação de tipos de argumentos e parâmetros de retorno se não
forem óbvios. Prefira usar convenções sempre que possível. (`cb` provavelmente
significa `callback function`, `num` provavelmente significa um `Número`).
4. Inclua o código de exemplo em **Utilização** como um arquio em seu repositório
-- algo como `example.js`. É ótimo ter um código README que os usuários podem
executar se clonarem seu repositório.
5. Seja criterioso no uso de badges. É fácil de [abusar](https://github.com/angular/angular).
Eles acrescentam ruído visual para o seu
README, e geralmente só funcionam se o usuário estiver lendo seu markdown em
um navegador on-line, uma vez que as imagens são geralmente hospedados em
outros lugares na internet. Para cada badge, considere: "qual o real valor este
badge está fornecendo para o leitor típico deste README"? Ter um badge CI para
mostrar o status de build / testes? Este alerta seria melhor se enviado por
e-mail para os mantenedores importantes do módulo ou criando uma issue
automaticamente -- sempre considere o público dos dados no seu README e
pergunte-se se há um fluxo de dados que pode atingir melhor o seu público-alvo.
6. API formatting is highly bikesheddable. Use whatever format you think is most
clear, but make sure your format expresses important subtleties:
a. quais parâmetros são opicionais, e quais seus valores default
b. mencione tipos que não são óbivios por convenção
c. para parâmetros de objetos `opts`, detalhe todas as chaves e valores aceitos
d. não se acanhe de fornecer um pequeno exemplo do uso de uma função da API se
seu uso não é óbvio ou totalmente coberto na seção **Utilização**.
No entanto, isso também pode ser um sinal forte que a função é complexa demais
e precisa ser reformulada, dividida em funções menores, ou removida
completamente
e. referencie agressivamente a terminologia! Em markdown você pode manter
[footnotes](https://daringfireball.net/projects/markdown/syntax#link) no
rodapéat do seu documento, por isso referencia-los várias vezes ao longo do
documento torna-se barato. Algumas das minhas preferências pessoais na
formatação de API podem ser encontradas
[aqui](https://github.com/noffle/common-readme/blob/master/api_formatting.md)
7. Se seu módulo é uma pequena coleção de funções stateless, tenha uma seção
**Utilização** como em [Node REPL session]
(https://github.com/noffle/bisecting-between#example). Chamadas e resultados
podem explicar a utilização de forma mais clara do que um arquivo de código-fonte
para ser executado.
8. Se o seu módulo fornece uma CLI (command line interface) ao invés de (ou
adicionalmente a) uma API, mostre exemplos de utilização como invocações de
linha de comando e suas saídas. Se você criar ou modificar um arquivo, use
`cat` para demonstrar o antes e o depois.
9. Não se esqueça de usar
[keywords](https://docs.npmjs.com/files/package.json#keywords) no `package.json`
para direcionar os caçadores de módulos à sua porta.
10. Quanto mais você mudar a sua API, mais trabalho será necessário para mantê-la
atualizada. Por isso você deve manter suas APIs pequenas e bem definidas desde
o início. Requisitos mudam ao longo do tempo. Se os requisitos *mudam* e
'fazer-uma-coisa-concreta' não faz mais sentido, simplesmente escreva um novo
módulo que faça o que você precisa. 'fazer-uma-coisa-concreta' continua um
módulo válido e valoroso para o ecosistema npm. E o custo de uma correção é
o de uma simples substituição de um módulo para outro.
11. Finally, please remember that your version control repository and its
embedded README will outlive your [repository host](https://github.com) and
any of the things you hyperlink to--especially images--so *inline* anything
that is essential to future users grokking your work.
## Bônus: *common-readme*
Não por coincidência, este também é o formato utilizado por
[**common-readme**](https://github.com/noffle/common-readme), um conjunto de
README guidelines e geradores utilitários de linha-de-comando. Se você gostar do
que vir aqui, você talvez possa poupar algum tempo escrevendo READMEs com o
`common-readme`. Você encontrará módulos de verdade neste formato também.
Você também poderá gostar de
[standard-readme](https://github.com/richardlitt/standard-readme), que é mais
estruturado, lintable, em um formato comum de README.
## Bônus: Exemplos
A teroria é boa... Mas com o que READMEs excelentes se parecem? Aqui estão alguns
que eu acredito que aplicam bem os princípios deste artigo:
- https://github.com/noffle/ice-box
- https://github.com/substack/quote-stream
- https://github.com/feross/bittorrent-dht
- https://github.com/mikolalysenko/box-intersect
- https://github.com/freeman-lab/pixel-grid
- https://github.com/mafintosh/torrent-stream
- https://github.com/pull-stream/pull-stream
- https://github.com/substack/tape
- https://github.com/yoshuawuyts/vmd
Conhece outros bons exemplos? [Envie um pull request](https://github.com/noffle/art-of-readme/pulls)!
## Bonus: The README Checklist
Um prático checklist para você conferir como seu README está:
- [ ] Uma linha explicando o propósito do módulo
- [ ] Ligações e contextualizações necessárias
- [ ] Termos pontencialmente desconhecidos linkados a fontes de informações
- [ ] Exemplo de utilização claro e *executável*
- [ ] Instruções de instalação
- [ ] Documentação extensiva da API
- [ ] Realizar [afunilamento cognitivo](https://github.com/noffle/art-of-readme#cognitive-funneling)
- [ ] Advertências e limitações explícitas
- [ ] Não depender de imagens para transmitir informações importantes
- [ ] Licença
## O autor
Eu sou o [noffle](http://blog.eight45.net/about/). Sou conhecido por
[blog](http://blog.eight45.net), [tweet](https://twitter.com/noffle), e
[hack](https://github.com/noffle).
Este pequeno projeto começou em maio em Berlim na squatconf, onde eu estava
escavando a forma como os monges Perl escrevem sua documentação e também
lamentando o estado dos meus READMEs no ecosistema Node. Isso me estimulou a
criar o [common-readme](https://github.com/noffle/common-readme). A seção
"README Tips" transbordou de dicas e eu achei que poderia ser útil coletá-las
em um artigo sobre escrever READMEs. Assim, Art of README nasceu!
## Leitura adicional
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## Notas de rodapé
1. <a name="footnote-1"></a>Obrigado,
[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)!
2. <a name="footnote-2"></a>Veja [The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html).
Entretanto, a maioria dos sistemas de hoje em dia não organiza maiúsculas antes
dos caracteres minúsculos, reduzindo a convenção a simplemente um apelo visual.
## Créditos
Um sincero agradecimento ao [@mafintosh](https://github.com/mafintosh) e
[@feross](https://github.com/feross) pelo incentivo que eu precisava para dar
vida a essa ideia e começar a escrever!
Obrigado aos incríveis leitores por reportar erros e enviar suas PRs :heart: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
Um agradecimento ao [@qihaiyan](https://github.com/qihaiyan) por traduzir o Art
of README para chinês! Os seguintes usuários também fizeram contribuições:
- [@BrettDong](https://github.com/brettdong) for revising punctuation in Chinese version.
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
Um agradecimento ao [@lennonjesus](https://github.com/lennonjesus) por traduzir
o Art of README para o Português Brasileiro! Os seguintes usuários também fizeram contribuições:
- [@rectius](https://github.com/rectius)
Um agradecimento ao [@jabiinfante](https://github.com/jabiinfante) por traduzir
o Art of README para o Espanhol!
Um agradecimento ao [@Ryuno-Ki](https://github.com/Ryuno-Ki) por traduzir
o Art of README para o Alemão! Os seguintes usuários também fizeram contribuições:
- [@randomC0der](https://github.com/randomC0der)
Um agradecimento ao [@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro) e
[@Ruben Madelaine](https://github.com/Ruben-Madelaine)
por traduzir o Art of README para o Francês!
Finalmente, obrigado a todos pelo feedback! Por favor, compartilhe seus
comentários através de [issues](https://github.com/noffle/art-of-readme/issues)!
## Contribuições são bem vindas!
Encontrou um erro? Algo não faz sentido? Envie um [pull
request](https://github.com/noffle/art-of-readme/pulls)!
## Licença
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
================================================
FILE: README-zh-TW.md
================================================
# README 的藝術
*此文章也有 [簡體中文](README-zh.md)、[日文](README-ja-JP.md)、[巴西葡萄牙文](README-pt-BR.md)、[西班牙文](README-es-ES.md)、[德文](README-de-DE.md) 以及 [法文](README-fr.md)。*
## 詞源
「README」這個詞是從何而來？
命名的日期**至少**可以追溯到 1970 年以及 [PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html)，不過也有可能來自更早之前放在打孔卡片上資訊豐富的紙質筆記，上面潦草地寫著「READ ME!」。
有位讀者<sup>[1](#footnote-1)</sup> 則認為 README 可能來自於 Lewis
Carroll 的《愛麗絲夢遊仙境》，其中一個藥水及蛋糕分別被貼上 *"DRINK ME"* 及 *"EAT ME"*。
README 從出現開始都是全大寫的形式，除了全大寫形式的視覺衝擊力外，UNIX 系統大寫字母會排在小寫字母前面，因此 README 能顯示在其他內容之前<sup>[[2]](#footnote-2)</sup>。
這樣做的用途很明顯： *「這是給用戶在進行下一步之前閱讀的重要訊息」*。讓我們來看一下現在的 *「重要訊息」* 是怎麼構成的。
## 給創作者及使用者
這是一篇關於 READMEs 的文章。關於它們的作用、為什麼它們絕對必要、以及如何精心製作它們。
這是為模組的創作者而寫，因為對於一個模組的創作者，你的工作是創作一些持久的東西，這是一種內在的動機，即使創作者無意分享他們的作品。一旦六個月過去，一個沒有文件的模組，作者也將開始覺得陌生。
這也是為了模組的使用者而寫，因為每個模組的作者也同時是一個模組的使用者。Node 有許多健康的相互依賴關係：沒有人會處在依賴樹的底部。
儘管內容主要是跟 Node 相關，作者認為也同樣適用於其他語言的生態系，
## 眾多模組，有好有壞
Node 的生態系源於他的模組們，[npm](https://npmjs.org) 是讓這一切 *開始* 的魔法。Node 開發者們每週都會評估專案中數十個模組。只要會寫 `npm install` 就能在日常生活中使用各種成熟的模組。
像其他容易使用的生態系，品質標準也各不相同。npm 盡最大努力打包所有模塊並分發到各處。然而，這些工具發現的種類繁多，有些閃亮又新，有些破損又生鏽。還有一些我們完全不知道他們在做什麼！
有些模組採用不準確或是無用的名字(猜猜看 `fudge` 這個模組是在做什麼？)、沒有文件、沒有測試、來源程式碼沒有註解或是難以理解的函式名稱。
許多模組沒有活躍的維護者。如果模組沒有人能夠回答問題以及解釋模組在做什麼，再加上沒有文件，模組將變成一個奇異的外星製品，無法使用且難以理解。
為什麼有些有文件的模組品質不好？有可能他們只有一行敘述：「按照十六進制對數字排序」。也有可能只有一段示範程式碼。這些都是毫無意義的改動，但卻使得模組使用者只能透過深入研究原始碼來了解其運作方式。撰寫出色的文件能讓使用者遠離原始碼，並透過抽象的方式了解模組的精彩之處。
Node 有「廣大」的生態系，它主要由一長串「只做好一件事」的模組組成。當然也有些 [例外](https://github.com/lodash/lodash)，儘管有些小領地，但 Node 王國主要還是由這些單一目的的平民統治著。
這有個後果：很難找到完全符合你需求的 *高品質* 模組。
**這也沒關係**。真的，低門檻及可發現性問題比只有少數特權人士可以參與的文化問題好。
此外，可發現性問題通常是容易解決的。
## 條條大路通 README.md
Node 社群已經用不同方式來解決可發現性的問題。
一些有經驗的 Node 開發者聯手創建有品質的模組[列表](https://github.com/sindresorhus/awesome-nodejs)。開發者利用多年研究數百的不同的模組，並分享每個類別裡最好的模組給新進者。也可能透過 RSS 訂閱以及被信任的社群成員視為有用的新模組郵件名單形式。
那社群圖譜呢？這個想法催生了 [node-modules.com](http://node-modules.com/)，一個替代 npm 搜尋的替代工具，利用 GitHub 的社群圖譜來找到你朋友喜歡或創建的模組。
當然還有 npm 內建的 [搜尋](https://npmjs.org) 功能：一個安全的預設功能，也是新開發者的常用入口。
無論用戶是透過 [npmjs.org](https://npmjs.org) 或 [github.com](https://github.com) 或其他地方找到模組，他們最終都會先看到你的 README，我們如何做到讓他們第一眼就印象深刻呢？
## 專業模組探討
## README：你的一站式服務
README 是模組使用者第一次(或許是唯一一次)查看你的創作。使用者想要模組滿組他們的需求，所以你必須準確地解釋模組滿足什麼需求，以及它如何有效地做到。
你的工作是：
1. 告訴他們這是什麼(利用場景)
2. 告訴他們實際使用上會是什麼樣子
3. 告訴他們要怎麼使用它
4. 告訴他們其他相關細節
這是*你的*工作。模組創作者有責任證明他們的作品是不嚴謹模組海洋中一顆閃亮的寶石。由於許多開發者會先看到你的 README，因此這會是公眾評量你作品的衡量標準。
## 簡潔
缺少 README 會是一個嚴重警訊，但即使有冗長的 README 也不代表高品質。理想的 README 盡可能簡短，但也不會太短。為詳細的文件單獨建立分頁，但請保持你的 README 簡潔。
## 向過去學習
有人說不研究歷史的人，注定重蹈覆徹。多年來，開發者一直撰寫文件，如果不回頭看看人們在 Node 之前是怎麼正確的撰寫文件，那就太浪費了。
Perl 儘管受到許多批評，某些方面上算是 Node 非實質的祖父母。兩者都是高階腳本語言，採用許多 UNIX 理念，為網路提供許多動力，並且都具有廣大的模組生態系。
事實證明 Perl 社群有許多[傳教士](http://perlmonks.org)在寫出[高品質 README](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm) 有豐富的經驗。CPAN 是一個值得一讀的優秀資源，可以了解一個社群如何編寫一致的高品質文件。
### 沒有 README 就沒有抽象
沒有 README 就代表開發者將需要深入你的程式碼才能理解。
Perl 的傳教士曾分享此智慧：
> 當有人使用你的模組但不需要閱讀原始碼，你的文件就完成了。
> 這非常重要，因為這讓你分離模組文件介面與內部實作。
> 這是一件好事，因為這意味著只要介面保持不變，你可以自由更改模組的內部結構。
-- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### 關鍵要素
一旦有了 README，勇敢的模組探索者將閱讀它來確認是否符合開發者的需求。這基本上變成一系列思維模式，每一步都讓他們更深入了解模組及其細節。
例如，我搜尋 2D 碰撞檢測模組引導我找到 [`collide-2d-aabb-aabb`](https://github.com/hackergrrl/collide-2d-aabb-aabb)。我開始從頭到尾檢查：
1. *名稱*：不言自明的名稱是最好的。`collide-2d-aabb-aabb`聽起來很不錯，儘管它假設我知道什麼是 「aabb」。如果名稱聽起來太模糊或不相關，這可能會是我繼續查找其他模組的警訊。
2. *一行敘述*：透過一行敘述說明模組，有助於更詳細地了解模組的作用。如 `collide-2d-aabb-aabb` 這樣描述：
> 確認移動的軸對齊邊界框 (AABB) 是否與其他 AABB 碰撞。
太棒了，這行敘述定義了 AABB 是什麼，以及模組的作用。現在可以來衡量模組是否適合我的程式碼。
3. *用法*：與其開始深入研究 API 文件，不如先看模組在實際運用會是什麼樣子。我可以快速確認範例 JS 是否適合所需的程式碼樣式及想要解決的問題。許多人對於像是 promises/callbacks 和 ES6 有許多意見。如果確實符合需求，那麼我可以進一步深入研究細節。
4. *API*：如果這個模組的名稱、描述以及使用方式都很吸引我。在這點上，我非常有可能使用這個模組。我只需要再檢視 API 以確保模組完全符合我的需求，並且可以輕鬆整合到我的程式碼中。API 區塊應該詳細說明模組的物件及函式、它們的簽名、回傳型別、callbacks 以及事件。當型別包含在不明顯的地方時，注意事項要描述清楚。
5. *安裝*：如果我已經閱讀到這，代表我要開始試用這個模組了。如果不是通用的安裝說明，那就需要在這個區塊描述。即使只是一個常規的 `npm install`，我也希望看到它被提及。對於新使用 Node 的用戶，放一個指向 npmjs.org 的連結及安裝指令，可以讓用戶更快理解 Node 模組怎麼運作。
6. *授權*：大多數的模組會放在最後敘述，但最好還是往前放一些。如果某個模組的授權協議與你的工作不相符，你可以很快將其排除在外。我通常堅持使用 MIT/BSD/X11/ISC。如果你不想授權，最好將其放到最前面來避免造成混淆。
## 認知漏斗
上面提及的順序不是隨機選擇的。
使用者使用很多模組，需要查看很多模組。
一旦你看過數百個模組，你就會注意到使用可預測模式的好處。
你還會開始建立自己的策略來決定什麼資訊是你想要的，以及哪些危險訊號會讓你快速略過這些模組。
因此，README 應該包含以下資訊：
1. 可預測的格式
2. 存在某些關鍵要素
你不需要使用*這種*格式，但盡量保持一致以節省用戶寶貴的認知週期。
這裡提到的呈現順序被稱為「認知漏斗」，可以想像成一個直立的漏斗，其中最寬的一端包含最廣泛的相關細節，而深入漏斗則呈現出更具體的細節，只有對你的作品有足夠興趣的讀者才能深入了解這部分的細節。最後，底部只能保留給那些對你的作品更深層背景(背景、致謝、參考書目......等)有興趣的使用者。
再一次，Perl 傳教士分享在這個問題上的智慧：
> Perl 模組文件對於細節的詳細程度通常從少至多
> 你的 SYNOPSIS 部分應該包含一個最小的使用範例
> (可能只有一行程式碼；省略掉不常用的例子或多數用戶不需要的內容)
> 敘述文字應該廣泛地描述你的模組，通常只需要幾個段落就好；
> 後續的段落要給出更多模組 routines 或函式、較長的程式碼範例或其他底層要素細節
> 理想情況下，稍微熟悉你模組的人應該能夠在不點擊「下一頁」的情況下大致了解你的模組
> 隨著繼續閱讀，他們應該會獲得越來越多的知識。
> -- `perlmodstyle`
## 在意使用者的時間
很棒；這些關鍵要素的排序應取決於它們讓使用者「短路」並放棄使用你的模組的速度。
這是不是聽起來很淒涼？但應該這麼想：當你懷著最佳的利他主義做這件事時，你的工作不是推銷作品給別人，而是讓他們盡可能客觀的評估你的創作。並覺得它是否滿足他們的需求，而不是為了最大化你的下載量或使用數。
並不是每個人都有這種心態，這需要有自我約束和實事求是的態度。你唯一要做的是簡潔描述它的承諾，這樣模組探險者們就可以在合適的時候選擇使用你的作品或另尋其他模組。
## 號召戰鬥
勇往直前，勇敢的模組探險者，透過優秀的文件來讓你的作品被看見及使用。
## 額外補充：其他好做法
除了本文的重點外，你也可以遵循(或不遵循)其他做法，以進一步提高 README 的品質標準並最大限度地提高對其他人的實用性：
1. 如果你的模組依賴於重要但不廣為人知的抽象或其他生態系，請考慮加上**背景**區塊。[`bisecting-between`](https://github.com/hackergrrl/bisecting-between) 的功能並不能從它的名字就可以立即看出來，所以需要有詳細**背景**區塊來定義及連結到大概念及抽象，讓使用者能夠使用及理解。如果 npm 上已經有相似的模組，這也是一個解釋建立此模組動機的好地方。
2. 積極建立連結！如果你談論到其他模組、想法或其他人時，在參考文字上加上連結，可以讓造訪者更容易的了解你的模組背後的想法。很少模組是憑空誕生的，所有的作品都源自於其他作品，因此幫助使用者了解模組的歷史和靈感是值得的。
3. 當參數及返回值的型別不明顯時，請加上相對應的資訊。盡可能符合常用約定(`cb` 可能表示 callback、`num` 可能表示 `Number`)。
4. 在**用法**中示範的程式碼，要以文件的形式放在 repo 中，例如：`example.js`。這樣當用戶 clone 專案後，就可以直接執行 README 提及的程式碼。
5. 謹慎使用徽章，它們很容易被[濫用](https://github.com/angular/angular)。他們也可能是瑣碎事物及無止盡爭吵的溫床。它們會在你的 README 上增加視覺干擾，並且只有在用戶用連網瀏覽器閱讀你的 Markdown 時才能看到徽章，因為圖片是存放在網路空間。對於發放每個徽章，需要考慮：這個徽章對閱讀 README 的標準讀者有什麼真正的價值？你有 CI 徽章來顯示 build/test 狀態嗎？透過發送電子郵件給維護者或自動創建 issue，讓此訊號能更好的被接收到。永遠要考慮 README 數據中的受眾，並問自己是否有一個流程讓數據更容易觸及到目標受眾。
6. API 格式是可高度循環的。使用你認為最清晰的任何格式，但要確保你的格式表達了重要的細節：
a. 哪些參數是可選的，以及他們的預設值
b. 如果型別不像約定呈現，需包含型別資訊
c. 對於 `opts` 物件參數，描述它所有可以接受的鍵與值
d. 如果在**用法**區塊不明顯或沒有完全涵蓋，不要迴避提供使用 API 函數的小範例。但這也是一個警訊，表示該函數過於複雜，需要重構、分解為更小的函數或完全刪除
e. 積極為專業術語加上連結！在 Markdown 中，你可以在文件底部加上[註腳](https://daringfireball.net/projects/markdown/syntax#link)，可以很方便的多次引用它們，我個人對於 API 格式的偏好可以查看[這裡](https://github.com/hackergrrl/common-readme/blob/master/api_formatting.md)
7. 如果你的模組是一個小的無狀態函數集合，將**用法**區塊以 [Node REPL session](https://github.com/hackergrrl/bisecting-between#example)格式提供函數的呼叫及結果會比執行原始碼文件更清楚傳達使用方式。
8. 如果你的模組提供 CLI(指令介面)而不是 API，請提供使用範例程式如何呼叫指令和輸出。如果你創建或修改一個文件，`cat` 它示範前後的變化。
9. 別忘記使用 `package.json` 的關鍵字來引導模組探索者找到你的模組。
10. 你更改的 API 越多，更新文件所需的工作就越多。代表你應該在早期就保持 API 精簡且定義明確。需求隨著時間變化，但不是預先設計到 API 中，而是要將它們設計到抽象類別：模組集合自身。當需求確實**變化**時並且「只做一個具體的事」不再符合需求，那麼只需要寫一個新模組來完成需求。「只做一個具體的事」模組仍然是 npm 生態系中一個有效且有價值的模型，而你的改進過程只是簡單用一個模組替換另一個模組。
11. 最後請記住，你的版本控制專案及內嵌入的 README 存在時間將比你的[專案託管](https://github.com)或任何你連結的事物，特別是圖片都要長久。因此*內連*任何對未來使用者了解你的作品至關重要的內容。
## 額外補充：*常見 README*
並非巧合，這也是 [**common-readme**](https://github.com/hackergrrl/common-readme) 使用的格式，一套 README 指南及方便的指令產生器。如果你喜歡這篇文章，你也可以透過 `common-readme` 來節省撰寫 README 的時間。你也可以找到使用這種格式的真實模組範例。
你也可以在 [standard-readme](https://github.com/richardlitt/standard-readme) 享受更架構化的通用 README 格式。
## 額外補充：範例
理論總是很好，但優秀的 README 長什麼樣子？以下是我認為很好體現本文原則的範例：
- https://github.com/hackergrrl/ice-box
- https://github.com/substack/quote-stream
- https://github.com/feross/bittorrent-dht
- https://github.com/mikolalysenko/box-intersect
- https://github.com/freeman-lab/pixel-grid
- https://github.com/mafintosh/torrent-stream
- https://github.com/pull-stream/pull-stream
- https://github.com/substack/tape
- https://github.com/yoshuawuyts/vmd
## 額外補充：README 檢查表
一個實用的檢查表來衡量你的 README：
- [ ] 用一行解釋模組的用途
- [ ] 必要的背景資料與連結
- [ ] 將可能不熟悉的術語連結到資訊來源
- [ ] 清楚、*可運行*的使用範例
- [ ] 安裝說明
- [ ] 詳細的 API 文件
- [ ] 執行[認知漏斗](#認知漏斗)
- [ ] 預先提及注意事項和限制
- [ ] 不依賴圖像傳遞重要訊息
- [ ] 授權
## 作者
你好，我是 [Kira](http://kira.solar)。
這個小專案從五月在柏林的 squatconf 開始，我在那裡深入研究 Perl 傳教士如何撰寫他們的文件，同時也感嘆 Node 生態系中 README 的狀態。這促使我建立 [common-readme](https://github.com/hackergrrl/common-readme)。雖然 "README Tips" 區塊充滿了提示，我仍然決定撰寫一篇關於撰寫 README 的文章。於是，Art of README 誕生了！
## 延伸閱讀
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## 註腳
1. <a name="footnote-1"></a>感謝 [Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)！
2. <a name="footnote-2"></a>查看 [The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html)。但是，現今大多數系統不會將大寫符號排在小寫符號之前，降低了這個約定的作用，全部大寫只能造成視覺衝擊性。
## 致謝
衷心感謝 [@mafintosh](https://github.com/mafintosh) 及 [@feross](https://github.com/feross) 鼓勵我構思這個想法及開始寫作！
感謝以下出色的讀者注意到錯誤並向我發出 PR :heart: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
感謝 [@qihaiyan](https://github.com/qihaiyan) 將 Art of README 翻譯成簡體中文！以下用戶也做出貢獻：
- [@BrettDong](https://github.com/brettdong) 修改中文版本的標點符號。
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
感謝 [@lennonjesus](https://github.com/lennonjesus) 將 Art of README 翻譯成巴西葡萄牙文！ 以下用戶也做出了貢獻：
- [@rectius](https://github.com/rectius)
感謝 [@jabiinfante](https://github.com/jabiinfante) 將 Art of README 翻譯成西班牙文！
感謝 [@Ryuno-Ki](https://github.com/Ryuno-Ki) 將 Art of README 翻譯成德文！ 以下用戶也做出了貢獻：
- [@randomC0der](https://github.com/randomC0der)
感謝 [@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro) 和 [@Ruben Madelaine](https://github.com/Ruben-Madelaine) 將 Art of README 翻譯成法文！
## 其他資源
一些讀者為 README 組件推薦了其他有用的資源：
- [Software Release Practice](https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme)
- [GNU Releases](https://www.gnu.org/prep/standards/html_node/Releases.html#index-README-file)
## 授權
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
================================================
FILE: README-zh.md
================================================
# README的艺术
<!--
Notes on Chinese formatting:
* GitHub does not support inline styles, leading to appearance of oblique text which is wrong in Chinese. I have replaced some of these <em>'s with bold text.
* Do not try to use line breaks for Chinese, or you get a bunch of extra spaces. If you find the source ugly without linebreak, blame markdown and let it be.
-->
## 词源
“README”（读我）这个词从何而来？
正式命名的日期可以追溯到**至少** 1970 年和 [PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html)；不过也有可能是来自更早之前放在打孔卡片上的便签纸，上面潦草地写着的“READ ME!”。
有位读者<sup>[[1]](#footnote-1)</sup>则提议说，“README”可能是来自于《爱丽丝漫游仙境》，其中一瓶药水和一个月饼上分别贴着“DRINK ME”（喝我）和“EAT ME”（吃我）的标签。
README 这个词从出现开始就一直是大写的。除了大写单词更醒目之外，UNIX 系统中大写字母会排在小写字母的前面，这样 README 就会显示在其它内容的前面
<sup>[[2]](#footnote-2)</sup>。
这样做的目的显而易见：“这是进行下一步之前的**重要信息**”。让我们来看一下现代的“**重要信息**”是怎么构成的。
## 针对创建者和使用者
这是一篇关于 README 的文章，介绍了做什么、为什么要做、怎么才能做好。
README 是写给模块创建者的。模块创建者的工作是创建一些能持续的东西，这是一种内在的动机，尽管作者可能并没想分享他的工作。一个没有文档的模块，往往时隔 6 个月后，就连作者自己都会觉得陌生。
README 也是写给模块使用者的。每个模块的作者同时也是该模块的使用者。Node 有一个非常健康的依赖关联度：没人会处在依赖树的底部。
尽管内容主要是跟 Node 相关，也同样适用于其它语言的生态系统。
## 很多模块，有好有坏
Node 的生态系统源于它的模块，[npm](https://npmjs.org)起着**关键**作用。Node 开发人员每周都会评估包含在他们的项目中的几十个模块。只要会写`npm install`，就能在日常工作中使用各种成熟的模块。
npm 可以非常方便的对模块进行打包和分发，但是质量却是良莠不齐：有新的、有旧的，甚至有些连用途都不知道。
什么是坏的模块？名字不清晰（猜猜 `fudge` 干什么的？）、没有文档、没有测试、没有注释，还有函数名字不易于理解。
很多模块没有活跃的维护者。如果一个模块没人回答问题或者说明模块的用途，再加上没有文档，就会变成一个火星上的东西，不可用并难以理解。
那些有文档的模块质量不好的原因又是什么？有的是因为文档里只有一行描述: `"sorts numbers by their hex
value"`。有的是因为文档里只是一些代码片段。这使得模块使用者只能通过阅读源代码来理解模块是怎么工作的。编写优秀的文档可以使用户不用阅读源码就能理解你模块的精妙之处。
Node的生态环境非常广泛：由大量的“只做一件事”的模块构成。[例外](https://github.com/lodash/lodash)当然也有，但总之都是那些“只做一件事”的大众统治着 Node 世界。
这就有一个易于发现的问题：找到你想要的**高质量**模块很困难。
**没事儿**。低门槛的生态、是否易于发现的问题总比出现封闭的社区文化问题好。
并且，事实证明可发现性问题总是容易解决的。
## 条条大路通向 README.md
Node 社区已经用不同的方法来着手解决可发现性的问题。
一些有经验的 Node 开发者合力创建了高质量模块的[列表](https://github.com/sindresorhus/awesome-nodejs)，筛选出了每个类别里的最好的模块。
受到社交图谱的启发，一个替代 `npm search` 的查找工具 [node-modules.com](http://node-modules.com/) 利用 GitHub 的社交图谱来查找你的朋友喜欢或创建的模块。
当然新的开发者还是可以用 npm 自带的 [search](https://npmjs.org) 功能。
用户无论是在 [npmjs.org](https://npmjs.org) 或者
[github.com](https://github.com) 或在其它途径发现了你的模块，首先映入他们眼帘的是 README。如何在这惊鸿一瞥中给他们留下深刻的印象？
## 专业模块探讨
### README：一站式服务
README 是使用者首先（或唯一）审视你作品的入口。用户希望模块能满足他们的需要，所以你要清楚的说明你的模块的主要作用和优势。
你要做的是：
1. 告诉他们这是什么 (使用场景)
2. 告诉他们在实际使用中是什么样子
3. 告诉他们使用的方法
4. 告诉他们其它相关的细节
这是 **你** 的工作。模块作者要证明他的作品在众多模块中是廖落星辰里的璀璨明珠。既然很多开发者第一眼看到的是你的 README，README 的编写质量决定了是否能给人留下好的第一印象。
### 简洁
README 必须要有，但是 README 内容的长度和质量没什么关系。理想的 README
应该尽可能的短。详细的文档可以在单独的页面里描述。保持 README 简洁。
### 以史为鉴
古人云：以史为鉴，可以知兴替。开发者编写文档已经有多年的历史了。值得我们花时间去看看在 Node 之前人们是怎么正确写文档的。
在某些方面，Node 跟 Perl 非常类似。都是高级脚本语言、采用了很多 UNIX 的理念、推动了互联网的发展、都有广泛的模块生态系统。
事实证明 Perl 社区的[圣僧们](http://perlmonks.org)在编写[高质量 README](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm)方面很有经验。CPAN 是值得仔细阅读的优秀资源， 可以学到一个社区如何能够始终如一的编写出高质量的文档。
### 没有 README 就没有抽象
没有 README 意味着开发者需要阅读源码才能理解你的模块。
Perl 圣僧们所分享的智慧：
> 只要你的文档是完备的，用户就可以直接使用你的模块而无需去阅读源码。这是非常重要的。通过文档可以在很大程度上将你的模块的外部接口和内部实现进行分离。这样就可以在保持接口不变的情况下，灵活的修改内部实现。
>
> 记住: 对模块进行定义的是文档而不是代码。
——[Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### 关键要素
有了 README 之后，勇敢的模块探险家会阅读它来判断模块是否满足开发者的需要。这是他们的思维模式，一步一步的去了解模块的细节。
比如说，当我想要一个 2D 碰撞检测模块时我找到了[`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb)。
我开始从头开始检查这个模块：
1. **取名**：名字要能做到“其义自见”。`collide-2d-aabb-aabb` 听起来是个不错的匹配，尽管它假设我知道"aabb"是什么意思。如果名字含义非常模糊或与我要找的没什么关系，我就会继续查找其它的模块了。
2. **一行流**：通过一句话简明扼要的说明了这个模块是做什么的。
`collide-2d-aabb-aabb` 的描述是：
> Determines whether a moving axis-aligned bounding box (AABB) collides with
> other AABBs.
太棒了——描述了 AABB 的定义是什么，并且说明了这个模块是做什么的。现在开始评测它是否适合我的代码：
3. **用法**：在开始探究 API 文档之前，最好看看这个模块在实际应用中是什么样子。我可以快速决定用JS写的示例程序是否符合我的代码样式和我要解决的问题。人们会在很多问题上意见相左，比如 promises/callbacks 和 ES6。如果符合我的要求，我会进一步去研究细节。
4. **API**：模块的名字，描述和使用方法都符合我的胃口。在这一点上我很乐意使用这个模块。我需要浏览API来确定这就是我需要的，并且很容易整合到我的代码中。API 部分应该详述模块的对象和函数，以及它们的签名，返回值，回调和事件。当类型不是特别明显的时候，也无需进行描述。注意事项要描述清楚。
5. **安装**：当我读到这儿的时候我就要开始试用这个模块了。 如果不是通用的安装说明，就需要在这儿进行描述。即使是一句简单的`npm install`也好。 对于使用Node的新用户来说，放一个指向npmjs.org的链接和安装命令，可以让用户快速上手使用模块。
6. **授权**：大多数模块把这个放在最末尾，但是最好还是往前放一些；非常有可能在把这个模块整合完后才发现授权协议不合适。我通常使用 MIT/BSD/X11/ISC。如果你的协议不是很宽容，最好是放到最前面。
## 认知漏斗
上面的顺序不是随意选择的。
模块使用者需要用到很多模块，需要查看很多模块。
当你查看了上百个模块之后，就可以体会到使用可以预测的模式的好处。
你也开始建立你自己的策略来快速的决定哪些是你需要的，哪些是不需要的。
因此，README应该包含以下信息:
1. 一个可以预测的格式
2. 某些关键元素
你不必非要用 **这个** 格式，但要保持统一以符合你的用户的认知习惯。
这儿介绍的顺序被简称为“认知漏斗”，
可以想象成是一个直立的漏斗，最宽的部分相关细节最宽泛，越往下移动细节越具体，只有对你的作品足够感兴趣的人才会关注这部分内容。最后，底部可以放一些作品背景的细节 (background，credits，biblio，...)
再一次，Perl圣僧们在这个主题上分享了他们的智慧：
> Perl模块的文档对于细节的描述是从少到多的。
> 你的简介部分应该包含一个小的例子程序
> （或许只有一行代码，省略掉不常用的用例或大多数用户用不到的功能）
> 描述部分应该从总体上描述你的模块，
> 通常只需要几个段落；在随后的章节中再详细描述模块的例程或方法，长的代码示例，或其它的资料。
> 理想情况下，在点“下一页”之前就能让人大体上了解你的模块。
> 随着用户继续阅读文档，他们能够渐进的获得更多的知识。
> —— `perlmodstyle`
## 珍惜时间
很棒；这些关键要素的排序应该让人尽快“短路”并放弃你的模块。
这听起来有点凄凉，不是吗？但是要这样想：你的工作，当你用利他主义思想来做的时候，不是为了销售给别人，而是为了让人们尽可能客观公正的评估你的作品，并判断是否满足他们的需要。而不是让你的下载量和用户数最大化。（老外的思想境界真是高）
并不是每个人都有这样的心态；这需要有自我约束和实事求是的态度。你唯一要做的是简洁的描述它的承诺，这样模块探险者们就可以或者使用你的作品或者别求他寻。
## 战斗的召唤！
前进，勇敢的模块探险家，通过出色的文档，让你的作品能够被发现和使用！
## 奖励: 其它好的实践
在文章的重点之外，有其它的实践你可以遵循(或不遵循)来提高你的README的质量，最大限度地发挥其作用。
1. 考虑包涵一个 **背景** 部分，如果你的模块依赖于重要但是不为人所熟知的抽象或生态系统。[`bisecting-between`](https://github.com/noffle/bisecting-between)的函数从它的名字上看不是特别明显，所以在 **背景** 部分会描述定义，并且给出具体概念和抽象的链接，以便需要的人去使用和获取。如果已经有相似的模块在npm上存在了，这儿也是一个非常适合描述建立模块的动机的地方。
2. 积极建立连接！如果你谈及其它的模块，想法，或者其他人的时候，在相关的引用内容上加上链接，这样访客就可以很容易的得到你的模块背后的想法。极少有模块是凭空诞生的：所有的作品来源于其它作品，因此很有必要让用户追溯你的模块的历史和灵感。
3. 包涵参数和返回值的类型的信息，当这些信息不明确的时候。 尽可能的符合约定(`cb` 代表回调函数，`num` 代表 `Number`)。
4. 在 **用法** 部分包含的示例代码，要在repo中以文件的形式体现 -- 例如`example.js`。这样当用户clone项目后，就可以直接运行README中提及的代码。
5. 使用徽章要慎重。经常会被[滥用](https://github.com/angular/angular)。它们会容易引起争论。它们在你的README中加入了视觉噪声，并且只有当用户在联网的浏览器里阅读你的markdown时才能看到徽章，因为图片是存放在互联网上的其它地方。对于每一个徽章，需要考虑：README中的徽章提供给典型读者的真实含义是什么？用一个CI徽章来显示build/test状态？这个信号更应该发邮件给维护者，或者自动创建一个issue -- 永远要考虑你的README中的数据的受众并且自问一下是否有一个流程能够让数据更好的送达到目标受众。
6. API 文档格式没有局限。使用任何你认为是清晰的格式，但是要包含重要的细节：
a. 参数是否可选，以及默认值
b. 包含类型信息，如果类型不能清楚的根据约定进行体现
c. 对于 `opts` 对象参数，描述它所接受的所有的 keys 和 values
d. 为每个API提供一个小的调用示例，如果它们的用法不明显或是在 **用法** 部分没有体现。
不过，也有可能是函数太复杂了，需要进行重构，划分成更细粒度的函数，或者整体删除。
e. 为特殊术语建立链接! 在markdown中你可以把[脚注](https://daringfireball.net/projects/markdown/syntax#link) 放在文档的末尾，可以很方便的多次引用它们。[这儿](https://github.com/noffle/common-readme/blob/master/api_formatting.md)有一些我的API文档格式的个人偏好。
7. 如果你的模块是无状态函数的一个小的集合，在**用法** 部分以 [Node REPLsession](https://github.com/noffle/bisecting-between#example) 格式放一些调用和返回值的示例比运行一个示例文件更清晰。
8. 如果你的模块提供了 CLI (command line interface)而不是 API，用命令调用的方式展示调用示例和输出。如果你创建了或更改了一个文件，`cat` 它来展示更改前后的变化。
9. 不要忘记使用 `package.json`中的[关键字](https://docs.npmjs.com/files/package.json#keywords)来盛情邀请模块探险者们。
10. API改的越多，越要努力的去更新文档 -- 言外之意是让你的API精简并及早给出具体定义。需求一直在变化，但是我们要做的是建立一个抽象层: 模块集合本身，而不是在API中做提前的假设。当需求**变更**时，并且'只做一件事'不能满足要求的时候，只需写一个新的模块。'只做一件事'对npm生态系统来说能够使一个模块是有效的和有价值的，并且你的改进过程只是简单的用一个模块来替换另一个模块。
11. 最后，请记住你的代码仓库和其中的README存在的时间要比你的[代码仓库托管主机](https://github.com)和你链接到的其它任何东西--特别是图片--的时间都要长久。所以**内嵌**任何对将来要获取你的作品的用户来说是重要的东西。
## 奖励：*common-readme*
不是巧合， 这也是
[**common-readme**](https://github.com/noffle/common-readme)用的文档格式，一个README写作指南和方便的command-line生成器。如果你喜欢这儿的内容，通过`common-readme`你可以节省编写README的时间。你也可以找到使用这个格式的真实的模块的例子。
你也可以在[标准Readme](https://github.com/richardlitt/standard-readme)中领略下更具结构化的通用Readme格式。
## 奖励：实例
理论总是好的，但优秀的README长什么样呢？这里有一些我认为体现了本文原则的实例：
* [https://github.com/noffle/ice-box](https://github.com/noffle/ice-box)
* [https://github.com/substack/quote-stream](https://github.com/substack/quote-stream)
* [https://github.com/feross/bittorrent-dht](https://github.com/feross/bittorrent-dht)
* [https://github.com/mikolalysenko/box-intersect](https://github.com/mikolalysenko/box-intersect)
* [https://github.com/freeman-lab/pixel-grid](https://github.com/freeman-lab/pixel-grid)
* [https://github.com/mafintosh/torrent-stream](https://github.com/mafintosh/torrent-stream)
* [https://github.com/pull-stream/pull-stream](https://github.com/pull-stream/pull-stream)
* [https://github.com/substack/tape](https://github.com/substack/tape)
* [https://github.com/yoshuawuyts/vmd](https://github.com/yoshuawuyts/vmd)
如果你遇到了认为不错的例子，请向我发起[pull request](https://github.com/noffle/art-of-readme/pulls)!
## 奖励：README清单
一个有用的清单用来衡量你的README:
- [x] 一句话解释模块的目的
- [x] 必要的背景资料或链接
- [x] 为潜在不熟悉的术语提供到信息来源的链接
- [x] 简洁可运行的实例
- [x] 安装说明
- [x] 详细的API文档
- [x] 对[认知漏斗](#认知漏斗)的执行
- [x] 前面提到的注意事项和限制
- [x] 不要依赖图片传递关键信息
- [x] 许可证
## 作者
我是 [noffle](http://blog.eight45.net/about/)。联系方式：
[blog](http://blog.eight45.net)，[tweet](https://twitter.com/noffle)，和
[hack](https://github.com/noffle).
这个小项目于5月份诞生在柏林的squatconf，在那儿我钻研Perl的圣僧们怎么编写他们的文档，同时叹息在Node生态系统中的我写的README。它促使我创建了
[common-readme](https://github.com/noffle/common-readme)。尽管"README Tips"部分满是tips，我仍然决定集中写一篇关于如何编写README的文章。于是，Art of README诞生了!
## 脚注
1. <a name="footnote-1"></a>感谢,[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)!
2. <a name="footnote-2"></a>参见[The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html)。然而，现在的多数系统不会将大写字母排在小写字母前面，弱化了这个约定的作用，全部大写只能是在视觉上更显著。
## 致谢
由衷地感谢 [@mafintosh](https://github.com/mafintosh) 和 [@feross](https://github.com/feross)，是他们的鼓励让我的这些想法得以落地，并开始写作!
感谢下面这些值得尊敬的读者，指正我的纰漏： :heart: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
感谢 [@qihaiyan](https://github.com/qihaiyan) 将《README的艺术》翻译成中文! 以下用户也为本文做出了贡献：
- [@BrettDong](https://github.com/brettdong) 修改了中文版的标点符号。
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
感谢 [@lennonjesus](https://github.com/lennonjesus) 将《README的艺术》翻译成巴西葡萄牙语！以下用户也为本文做出了贡献：
- [@rectius](https://github.com/rectius)
感谢 [@jabiinfante](https://github.com/jabiinfante) 将《README的艺术》翻译成西班牙语！
感谢 [@Ryuno-Ki](https://github.com/Ryuno-Ki) 将《README的艺术》翻译成德语！以下用户也对本文做出了贡献：
谢谢[@Manfred Madelaine]（https://github.com/Manfred-Madelaine-pro）和
[@Ruben Madelaine]（https://github.com/Ruben-Madelaine）
将《README的艺术》翻译成法语！
- [@randomC0der](https://github.com/randomC0der)
最后，对于你们所有的反馈表示由衷感谢! 请在 [issue](https://github.com/noffle/art-of-readme/issues) 中分享你们的评论!
## 欢迎参与!
发现了错误? 存在某些无意义的东西? 向我发起一个[pull request](https://github.com/noffle/art-of-readme/pulls)吧!
## 许可证
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
================================================
FILE: README.md
================================================
# Art of README
*This article can also be read in [Chinese](README-zh.md),
[Japanese](README-ja-JP.md),
[Brazilian Portuguese](README-pt-BR.md), [Spanish](README-es-ES.md),
[German](README-de-DE.md), [French](README-fr.md) and [Traditional Chinese](README-zh-TW.md).*
## Etymology
Where does the term "README" come from?
The nomenclature dates back to *at least* the 1970s [and the
PDP-10](http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html),
though it may even harken back to the days of informative paper notes placed atop
stacks of punchcards, "READ ME!" scrawled on them, describing their use.
A reader<sup>[1](#footnote-1)</sup> suggested that the title README may be a playful nudge toward Lewis
Carroll's *Alice's Adventures in Wonderland*, which features a potion and a cake
labelled *"DRINK ME"* and *"EAT ME"*, respectively.
The pattern of README appearing in all-caps is a consistent facet throughout
history. In addition to the visual strikingness of using all-caps, UNIX systems
would sort capitals before lower case letters, conveniently putting the README
before the rest of the directory's content<sup>[2](#footnote-2)</sup>.
The intent is clear: *"This is important information for the user to read before
proceeding."* Let's explore together what constitutes "important information" in
this modern age.
## For creators, for consumers
This is an article about READMEs. About what they do, why they are an absolute
necessity, and how to craft them well.
This is written for module creators, for as a builder of modules, your job is to
create something that will last. This is an inherent motivation, even if the
author has no intent of sharing their work. Once 6 months pass, a module without
documentation begins to look new and unfamiliar.
This is also written for module consumers, for every module author is also a
module consumer. Node has a very healthy degree of interdependency: no one lives
at the bottom of the dependency tree.
Despite being focused on Node, the author contends that its lessons apply
equally well to other programming ecosystems, as well.
## Many modules: some good, some bad
The Node ecosystem is powered by its modules. [npm](https://npmjs.org) is the
magic that makes it all *go*. In the course of a week, Node developers evaluate
dozens of modules for inclusion in their projects. This is a great deal of power
being churned out on a daily basis, ripe for the plucking, just as fast as one
can write `npm install`.
Like any ecosystem that is extremely accessible, the quality bar varies. npm
does its best to nicely pack away all of these modules and ship them far and
wide. However, the tools found are widely varied: some are shining and new,
others broken and rusty, and still others are somewhere in between. There are
even some that we don't know what they do!
For modules, this can take the form of inaccurate or unhelpful names (any
guesses what the `fudge` module does?), no documentation, no tests, no source
code comments, or incomprehensible function names.
Many don't have an active maintainer. If a module has no human available to
answer questions and explain what a module does, combined with no remnants of
documentation left behind, a module becomes a bizarre alien artifact, unusable
and incomprehensible by the archaeologist-hackers of tomorrow.
For those modules that do have documentation, where do they fall on the quality
spectrum? Maybe it's just a one-liner description: `"sorts numbers by their hex
value"`. Maybe it's a snippet of example code. These are both improvements upon
nothing, but they tend to result in the worst-case scenario for a modern day
module spelunker: digging into the source code to try and understand how it
actually works. Writing excellent documentation is all about keeping the users
*out* of the source code by providing instructions sufficient to enjoy the
wonderful abstractions that your module brings.
Node has a "wide" ecosystem: it's largely made up of a very long list of
independent do-one-thing-well modules flying no flags but their own. There are
[exceptions](https://github.com/lodash/lodash), but despite these minor fiefdoms,
it is the single-purpose commoners who, given their larger numbers, truly rule the
Node kingdom.
This situation has a natural consequence: it can be hard to find *quality* modules
that do exactly what you want.
**This is okay**. Truly. A low bar to entry and a discoverability problem is
infinitely better than a culture problem, where only the privileged few may
participate.
Plus, discoverability -- as it turns out -- is easier to address.
## All roads lead to README.md
The Node community has responded to the challenge of discoverability in
different ways.
Some experienced Node developers band together to create [curated
lists](https://github.com/sindresorhus/awesome-nodejs) of quality modules.
Developers leverage their many years examining hundreds of different modules to
share with newcomers the *crème de la crème*: the best modules in each category.
This might also take the form of RSS feeds and mailing lists of new modules deemed
to be useful by trusted community members.
How about the social graph? This idea spurred the creation of
[node-modules.com](http://node-modules.com/), a npm search replacement that
leverages your GitHub social graph to find modules your friends like or have
made.
Of course there is also npm's built-in [search](https://npmjs.org)
functionality: a safe default, and the usual port of entry for new developers.
No matter your approach, regardless whether a module spelunker enters the module
underground at [npmjs.org](https://npmjs.org),
[github.com](https://github.com), or somewhere else, this would-be user will
eventually end up staring your README square in the face. Since your users
will inevitably find themselves here, what can be done to make their first
impressions maximally effective?
## Professional module spelunking
### The README: Your one-stop shop
A README is a module consumer's first -- and maybe only -- look into your
creation. The consumer wants a module to fulfill their need, so you must explain
exactly what need your module fills, and how effectively it does so.
Your job is to
1. tell them what it is (with context)
2. show them what it looks like in action
3. show them how they use it
4. tell them any other relevant details
This is *your* job. It's up to the module creator to prove that their work is a
shining gem in the sea of slipshod modules. Since so many developers' eyes will
find their way to your README before anything else, quality here is your
public-facing measure of your work.
### Brevity
The lack of a README is a powerful red flag, but even a lengthy README is not
indicative of there being high quality. The ideal README is as short as it can
be without being any shorter. Detailed documentation is good -- make separate
pages for it! -- but keep your README succinct.
### Learn from the past
It is said that those who do not study their history are doomed to make its
mistakes again. Developers have been writing documentation for quite some number
of years. It would be wasteful to not look back a little bit and see what people
did right before Node.
Perl, for all of the flak it receives, is in some ways the spiritual grandparent
of Node. Both are high-level scripting languages, adopt many UNIX idioms, fuel
much of the internet, and both feature a wide module ecosystem.
It so turns out that the [monks](http://perlmonks.org) of the Perl community
indeed have a great deal of experience in writing [quality
READMEs](http://search.cpan.org/~kane/Archive-Tar/lib/Archive/Tar.pm). CPAN is a
wonderful resource that is worth reading through to learn more about a community
that wrote consistently high-calibre documentation.
### No README? No abstraction
No README means developers will need to delve into your code in order to
understand it.
The Perl monks have wisdom to share on the matter:
> Your documentation is complete when someone can use your module without ever
> having to look at its code. This is very important. This makes it possible for
> you to separate your module's documented interface from its internal
> implementation (guts). This is good because it means that you are free to
> change the module's internals as long as the interface remains the same.
>
> Remember: the documentation, not the code, defines what a module does.
-- [Ken Williams](http://mathforum.org/ken/perl_modules.html#document)
### Key elements
Once a README is located, the brave module spelunker must scan it to discern if
it matches the developer's needs. This becomes essentially a series of pattern
matching problems for their brain to solve, where each step takes them deeper
into the module and its details.
Let's say, for example, my search for a 2D collision detection module leads me
to [`collide-2d-aabb-aabb`](https://github.com/hackergrrl/collide-2d-aabb-aabb). I
begin to examine it from top to bottom:
1. *Name* -- self-explanatory names are best. `collide-2d-aabb-aabb` sounds
promising, though it assumes I know what an "aabb" is. If the name sounds too
vague or unrelated, it may be a signal to move on.
2. *One-liner* -- having a one-liner that describes the module is useful for
getting an idea of what the module does in slightly greater detail.
`collide-2d-aabb-aabb` says it
> Determines whether a moving axis-aligned bounding box (AABB) collides with
> other AABBs.
Awesome: it defines what an AABB is, and what the module does. Now to gauge how
well it'd fit into my code:
3. *Usage* -- rather than starting to delve into the API docs, it'd be great to
see what the module looks like in action. I can quickly determine whether the
example JS fits the desired style and problem. People have lots of opinions
on things like promises/callbacks and ES6. If it does fit the bill, then I
can proceed to greater detail.
4. *API* -- the name, description, and usage of this module all sound appealing
to me. I'm very likely to use this module at this point. I just need to scan
the API to make sure it does exactly what I need and that it will integrate
easily into my codebase. The API section ought to detail the module's objects
and functions, their signatures, return types, callbacks, and events in
detail. Types should be included where they aren't obvious. Caveats should be
made clear.
5. *Installation* -- if I've read this far down, then I'm sold on trying out the
module. If there are nonstandard installation notes, here's where they'd go,
but even if it's just a regular `npm install`, I'd like to see that mentioned,
too. New users start using Node all the time, so having a link to npmjs.org
and an install command provides them the resources to figure out how Node
modules work.
6. *License* -- most modules put this at the very bottom, but this might
actually be better to have higher up; you're likely to exclude a module VERY
quickly if it has a license incompatible with your work. I generally stick to
the MIT/BSD/X11/ISC flavours. If you have a non-permissive license, stick it
at the very top of the module to prevent any confusion.
## Cognitive funneling
The ordering of the above was not chosen at random.
Module consumers use many modules, and need to look at many modules.
Once you've looked at hundreds of modules, you begin to notice that the mind
benefits from predictable patterns.
You also start to build out your own personal heuristic for what information you
want, and what red flags disqualify modules quickly.
Thus, it follows that in a README it is desirable to have:
1. a predictable format
2. certain key elements present
You don't need to use *this* format, but try to be consistent to save your users
precious cognitive cycles.
The ordering presented here is lovingly referred to as "cognitive funneling,"
and can be imagined as a funnel held upright, where the widest end contains the
broadest more pertinent details, and moving deeper down into the funnel presents
more specific details that are pertinent for only a reader who is interested
enough in your work to have reached that deeply in the document. Finally, the
bottom can be reserved for details only for those intrigued by the deeper
context of the work (background, credits, biblio, etc.).
Once again, the Perl monks have wisdom to share on the subject:
> The level of detail in Perl module documentation generally goes from
> less detailed to more detailed. Your SYNOPSIS section should
> contain a minimal example of use (perhaps as little as one line of
> code; skip the unusual use cases or anything not needed by most
> users); the DESCRIPTION should describe your module in broad terms,
> generally in just a few paragraphs; more detail of the module's
> routines or methods, lengthy code examples, or other in-depth
> material should be given in subsequent sections.
>
> Ideally, someone who's slightly familiar with your module should be
> able to refresh their memory without hitting "page down". As your
> reader continues through the document, they should receive a
> progressively greater amount of knowledge.
> -- from `perlmodstyle`
## Care about people's time
Awesome; the ordering of these key elements should be decided by how quickly
they let someone 'short circuit' and bail on your module.
This sounds bleak, doesn't it? But think about it: your job, when you're doing
it with optimal altruism in mind, isn't to "sell" people on your work. It's to
let them evaluate what your creation does as objectively as possible, and decide
whether it meets their needs or not -- not to, say, maximize your downloads or
userbase.
This mindset doesn't appeal to everyone; it requires checking your ego at the
door and letting the work speak for itself as much as possible. Your only job is
to describe its promise as succinctly as you can, so module spelunkers can
either use your work when it's a fit, or move on to something else that does.
## Call to arms!
Go forth, brave module spelunker, and make your work discoverable and usable
through excellent documentation!
## Bonus: other good practices
Outside of the key points of the article, there are other practices you can
follow (or not follow) to raise your README's quality bar even further and
maximize its usefulness to others:
1. Consider including a **Background** section if your module depends on
important but not widely known abstractions or other ecosystems. The function
of [`bisecting-between`](https://github.com/hackergrrl/bisecting-between) is not
immediately obvious from its name, so it has a detailed *Background* section
to define and link to the big concepts and abstractions one needs to
understand to use and grok it. This is also a great place to explain the
module's motivation if similar modules already exist on npm.
2. Aggressively linkify! If you talk about other modules, ideas, or people, make
that reference text a link so that visitors can more easily grok your module
and the ideas it builds on. Few modules exist in a vacuum: all work comes
from other work, so it pays to help users follow your module's history and
inspiration.
3. Include information on types of arguments and return parameters if it's not
obvious. Prefer convention wherever possible (`cb` probably means callback
function, `num` probably means a `Number`, etc.).
4. Include the example code in **Usage** as a file in your repo -- maybe as
`example.js`. It's great to have README code that users can actually run if
they clone the repository.
5. Be judicious in your use of badges. They're easy to
[abuse](https://github.com/angular/angular). They can also be a breeding
ground for bikeshedding and endless debate. They add visual noise to your
README and generally only function if the user is reading your Markdown in a
browser online, since the images are often hosted elsewhere on the
internet. For each badge, consider: "what real value is this badge providing
to the typical viewer of this README?" Do you have a CI badge to show build/test
status? This signal would better reach important parties by emailing
maintainers or automatically creating an issue. Always consider the
audience of the data in your README and ask yourself if there's a flow for
that data that can better reach its intended audience.
6. API formatting is highly bikesheddable. Use whatever format you think is
clearest, but make sure your format expresses important subtleties:
a. which parameters are optional, and their defaults
b. type information, where it is not obvious from convention
c. for `opts` object parameters, all keys and values that are accepted
d. don't shy away from providing a tiny example of an API function's use if
it is not obvious or fully covered in the **Usage** section.
However, this can also be a strong signal that the function is too complex
and needs to be refactored, broken into smaller functions, or removed
altogether
e. aggressively linkify specialized terminology! In markdown you can keep
[footnotes](https://daringfireball.net/projects/markdown/syntax#link) at
the bottom of your document, so referring to them several times throughout
becomes cheap. Some of my personal preferences on API formatting can be
found
[here](https://github.com/hackergrrl/common-readme/blob/master/api_formatting.md)
7. If your module is a small collection of stateless functions, having a
**Usage** section as a [Node REPL
session](https://github.com/hackergrrl/bisecting-between#example) of function
calls and results might communicate usage more clearly than a source code
file to run.
8. If your module provides a CLI (command line interface) instead of (or in
addition to) a programmatic API, show usage examples as command invocations
and their output. If you create or modify a file, `cat` it to demonstrate
the change before and after.
9. Don't forget to use `package.json`
[keywords](https://docs.npmjs.com/files/package.json#keywords) to direct
module spelunkers to your doorstep.
10. The more you change your API, the more work you need to exert updating
documentation -- the implication here is that you should keep your APIs
small and concretely defined early on. Requirements change over time, but
instead of front-loading assumptions into the APIs of your modules, load
them up one level of abstraction: the module set itself. If the requirements
*do* change and 'do-one-concrete-thing' no longer makes sense, then simply
write a new module that does the thing you need. The 'do-one-concrete-thing'
module remains a valid and valuable model for the npm ecosystem, and your
course correction cost you nothing but a simple substitution of one module for
another.
11. Finally, please remember that your version control repository and its
embedded README will outlive your [repository host](https://github.com) and
any of the things you hyperlink to -- especially images -- so *inline* anything
that is essential to future users grokking your work.
## Bonus: *common-readme*
Not coincidentally, this is also the format used by
[**common-readme**](https://github.com/hackergrrl/common-readme), a set of README
guidelines and handy command-line generator. If you like what's written here,
you may save some time writing READMEs with `common-readme`. You'll find
real module examples with this format, too.
You may also enjoy
[standard-readme](https://github.com/richardlitt/standard-readme), which is a
more structured, lintable take on a common README format.
## Bonus: Exemplars
Theory is well and good, but what do excellent READMEs look like? Here are some
that I think embody the principles of this article well:
- https://github.com/hackergrrl/ice-box
- https://github.com/substack/quote-stream
- https://github.com/feross/bittorrent-dht
- https://github.com/mikolalysenko/box-intersect
- https://github.com/freeman-lab/pixel-grid
- https://github.com/mafintosh/torrent-stream
- https://github.com/pull-stream/pull-stream
- https://github.com/substack/tape
- https://github.com/yoshuawuyts/vmd
## Bonus: The README Checklist
A helpful checklist to gauge how your README is coming along:
- [ ] One-liner explaining the purpose of the module
- [ ] Necessary background context & links
- [ ] Potentially unfamiliar terms link to informative sources
- [ ] Clear, *runnable* example of usage
- [ ] Installation instructions
- [ ] Extensive API documentation
- [ ] Performs [cognitive funneling](https://github.com/hackergrrl/art-of-readme#cognitive-funneling)
- [ ] Caveats and limitations mentioned up-front
- [ ] Doesn't rely on images to relay critical information
- [ ] License
## The author
Hi, I'm [Kira](http://kira.solar).
This little project began back in May in Berlin at squatconf, where I was
digging into how Perl monks write their documentation and also lamenting the
state of READMEs in the Node ecosystem. It spurred me to create
[common-readme](https://github.com/hackergrrl/common-readme). The "README Tips"
section overflowed with tips though, which I decided could be usefully collected
into an article about writing READMEs. Thus, Art of README was born!
## Further Reading
- [README-Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)
- [Documentation First](http://joeyh.name/blog/entry/documentation_first/)
## Footnotes
1. <a name="footnote-1"></a>Thanks,
[Sixes666](https://www.reddit.com/r/node/comments/55eto9/nodejs_the_art_of_readme/d8akpz6)!
2. <a name="footnote-2"></a>See [The Jargon File](http://catb.org/~esr/jargon/html/R/README-file.html).
However, most systems today will not sort capitals before all lowercase
characters, reducing this convention's usefulness to just the visual
strikingness of all-caps.
## Credits
A heartfelt thank you to [@mafintosh](https://github.com/mafintosh) and
[@feross](https://github.com/feross) for the encouragement I needed to get this
idea off the ground and start writing!
Thank you to the following awesome readers for noticing errors and sending me
PRs :heart: :
- [@ungoldman](https://github.com/ungoldman)
- [@boidolr](https://github.com/boidolr)
- [@imjoehaines](https://github.com/imjoehaines)
- [@radarhere](https://github.com/radarhere)
- [@joshmanders](https://github.com/joshmanders)
- [@ddbeck](https://github.com/ddbeck)
- [@RichardLitt](https://github.com/RichardLitt)
- [@StevenMaude](https://github.com/StevenMaude)
- [@KrishMunot](https://github.com/KrishMunot)
- [@chesterhow](https://github.com/chesterhow)
- [@sjsyrek](https://github.com/sjsyrek)
- [@thenickcox](https://github.com/thenickcox)
Thank you to [@qihaiyan](https://github.com/qihaiyan) for translating Art of
README to Chinese! The following users also made contributions:
- [@BrettDong](https://github.com/brettdong) for revising punctuation in Chinese version.
- [@Alex-fun](https://github.com/Alex-fun)
- [@HmyBmny](https://github.com/HmyBmny)
- [@vra](https://github.com/vra)
Thank you to [@lennonjesus](https://github.com/lennonjesus) for translating Art
of README to Brazilian Portuguese! The following users also made contributions:
- [@rectius](https://github.com/rectius)
Thank you to [@jabiinfante](https://github.com/jabiinfante) for translating Art
of README to Spanish!
Thank you to [@Ryuno-Ki](https://github.com/Ryuno-Ki) for translating Art of
README to German! The following users also made contributions:
- [@randomC0der](https://github.com/randomC0der)
Thank you to [@Manfred Madelaine](https://github.com/Manfred-Madelaine-pro) and
[@Ruben Madelaine](https://github.com/Ruben-Madelaine)
for translating Art of README to French!
## Other Resources
Some readers have suggested other useful resources for README composition:
- [Software Release Practice](https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme)
- [GNU Releases](https://www.gnu.org/prep/standards/html_node/Releases.html#index-README-file)
## License
[Creative Commons Attribution License](http://creativecommons.org/licenses/by/2.0/)
gitextract_lldhirn_/ ├── README-de-DE.md ├── README-es-ES.md ├── README-fr.md ├── README-ja-JP.md ├── README-pt-BR.md ├── README-zh-TW.md ├── README-zh.md └── README.md
Condensed preview — 8 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (173K chars).
[
{
"path": "README-de-DE.md",
"chars": 27864,
"preview": "# Die Kunst des README\n\n*Dieser Artikel wurde aus dem [Englischen](README.md) übersetzt.*\n\n*Dieser Artikel kann auch auf"
},
{
"path": "README-es-ES.md",
"chars": 27337,
"preview": "# El arte del README\n\n*Este artículo ha sido traducido desde el [inglés](README.md) y tambien lo\npuedes encontrar en [ch"
},
{
"path": "README-fr.md",
"chars": 28179,
"preview": "# L'art du README\n\n*Cet article a été traduit à partir de la version [Anglaise](README.md) \net est également disponible "
},
{
"path": "README-ja-JP.md",
"chars": 14186,
"preview": "# Art of README\n\n## 語源\n\n”README”の語源は何でしょうか？\n\nこの命名は、 _少なくとも_ 1970 年代の[PDP-10](http://pdp-10.trailing-edge.com/decuslib10-"
},
{
"path": "README-pt-BR.md",
"chars": 25713,
"preview": "# Art of README\n\n*Este artigo foi traduzido do [Inglês](README.md) e traduzido para [Chinês](README-zh.md),\n[Português]("
},
{
"path": "README-zh-TW.md",
"chars": 10364,
"preview": "# README 的藝術\n\n*此文章也有 [簡體中文](README-zh.md)、[日文](README-ja-JP.md)、[巴西葡萄牙文](README-pt-BR.md)、[西班牙文](README-es-ES.md)、[德文](R"
},
{
"path": "README-zh.md",
"chars": 10889,
"preview": "# README的艺术\n<!--\nNotes on Chinese formatting:\n\n* GitHub does not support inline styles, leading to appearance of oblique"
},
{
"path": "README.md",
"chars": 24355,
"preview": "# Art of README\n\n*This article can also be read in [Chinese](README-zh.md),\n[Japanese](README-ja-JP.md),\n[Brazilian Port"
}
]
About this extraction
This page contains the full source code of the hackergrrl/art-of-readme GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 8 files (164.9 KB), approximately 52.8k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.