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