{"id":13432542,"url":"https://github.com/hackergrrl/common-readme","last_synced_at":"2025-04-05T06:10:08.644Z","repository":{"id":43491532,"uuid":"52996540","full_name":"hackergrrl/common-readme","owner":"hackergrrl","description":":star2: « a common readme for node »","archived":false,"fork":false,"pushed_at":"2021-11-25T20:13:51.000Z","size":56,"stargazers_count":384,"open_issues_count":0,"forks_count":250,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-13T16:25:47.066Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hackergrrl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-02T21:07:50.000Z","updated_at":"2024-05-07T16:08:00.000Z","dependencies_parsed_at":"2022-07-20T05:17:54.098Z","dependency_job_id":null,"html_url":"https://github.com/hackergrrl/common-readme","commit_stats":null,"previous_names":["noffle/common-readme"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackergrrl%2Fcommon-readme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackergrrl%2Fcommon-readme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackergrrl%2Fcommon-readme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackergrrl%2Fcommon-readme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hackergrrl","download_url":"https://codeload.github.com/hackergrrl/common-readme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294541,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T02:01:13.123Z","updated_at":"2025-04-05T06:10:08.624Z","avatar_url":"https://github.com/hackergrrl.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","🛵 CLI","others","Tools"],"sub_categories":[],"readme":"\u003ch4 align=\"center\"\u003e\n  \u003cimg alt=\"common readme\" src=\"common-readme.png\"\u003e\n\u003c/h4\u003e\n\n***Module consumers!*** Frustrated by each module having its own wildly\nunique README format? Annoyed by modules that omit critical sections like\n**API** or **Examples**? Stuck scrolling through API docs before you *even know\nwhat the module does*?\n\n***Module authors!*** Tired of making up your readme format every time you\nwrite it? Do you just want consistent readmes pre-populated with your module's\nname, description and license without worrying about the structure every time?\n\n---\n\nWhat if there was a common format for the benefit of producers and consumers?\n\nA *common readme* for node modules.\n\nThis can save everybody time by adhering to 4 principles:\n\n1. **No lock in.** No special formats or tooling; run `common-readme` once for\n   pure vanilla markdown.\n2. **No surprises.** Pull as many details out of `package.json` -- like name,\n   description, and license -- as possible. No time wasted on configuration.\n3. **Cognitive funnelling.** Start with the most general information at the top\n   (Name, Description, Examples) and if the reader maintains interest, narrow\n   down to specifics (API, Installation). This makes it easy for readers to\n   \"short circuit\" and continue the hunt for the right module elsewhere without\n   wasting time delving into unnecessary details.\n4. **Consistency.** Your brain can scan a document much faster when it can\n   anticipate its structure.\n\n## Common format\n\ncommon-readme operates on the principle of *cognitive funneling*.\n\n\u003e Ideally, someone who's slightly familiar with your module should be able to\n\u003e refresh their memory without hitting \"page down\".  As your reader continues\n\u003e through the document, they should receive a progressively greater amount of\n\u003e knowledge. -- `perlmodstyle`\n\nHere are some READMEs generated using common-readme:\n\n- [`collide-2d-aabb-aabb`](https://github.com/noffle/collide-2d-aabb-aabb)\n- [`goertzel`](https://github.com/noffle/goertzel)\n- [`twitter-kv`](https://github.com/noffle/twitter-kv)\n\n*([Submit a pull request](https://github.com/noffle/common-readme/pulls) and add\nyours here!)*\n\n## Usage\n\nWith [npm](https://npmjs.org/) installed, run\n\n    $ npm install -g common-readme\n\n`common-readme` is a command line program. You run it when you've started a new\nmodule that has a `package.json` set up.\n\nWhen run, a brand new README is generated and written to your terminal. You can\nredirect this to `README.md` and use it as a basis for your new module.\n\n    $ common-readme \u003e README.md\n\nThis brand new readme will be automatically populated with values from\n`package.json` such as `name`, `description`, and `license`. Stub sections will\nbe created for everything else (Usage, API, etc), ready for you to fill in.\n\n## Why?\n\nThis isn't a crazy new idea. Other ecosystems like [Perl's\nCPAN](http://perldoc.perl.org/perlmodstyle.html) have been benefiting from a\ncommon readme format for years. Furthermore:\n\n1. The node community is powered by us people and the modules we share. It's our\n   documentation that links us together. Our README is the first thing\n   developers see and it should be maximally effective at communicating its\n   purpose and function.\n\n2. There is much wisdom to be found from the many developers who have written\n   many many modules. Common readme aims to distill that experience into a\n   common format that stands to benefit us all; especially newer developers!\n\n3. Writing the same boilerplate is a waste of every author's time -- we might as\n   well generate the common pieces and let the author focus on the content.\n\n4. Scanning through modules on npm is a part of every node developer's regular\n   development cycle. Having a consistent format lets the brain focus on content\n   instead of structure.\n\n## The Art of README\n\nFor even more background, wisdom, and ideas, take a look at the article that\ninspired common-readme:\n\n- [*Art of README*](https://github.com/noffle/art-of-readme).\n\n## Install\n\nWith [npm](https://npmjs.org/) installed, run\n\n```shell\nnpm install -g common-readme\n```\n\nYou can now execute the `common-readme` command.\n\n## Acknowledgments\n\nA standard readme format for the Node community isn't a new idea. Inspiration\ncame from many conversations and unrealized efforts in the community:\n\n- \u003chttps://github.com/feross/standard/issues/141\u003e\n- [richardlitt/standard-readme](https://github.com/RichardLitt/readme-standard)\n- [zwei/standard-readme](https://github.com/zcei/standard-readme)\n\nThis, in addition to my own experiences evaluating hundreds of node modules and\ntheir READMEs.\n\nI was partly inspired by the audacity of the honey-badger-don't-care efforts of\n[standard](https://github.com/feross/standard).\n\nI also did a great deal of Perl archaeology -- it turns out the monks of the\nPerl community already did much of the hard work of [figuring out great\nREADMEs](http://perldoc.perl.org/perlmodstyle.html) and the wisdom around small\nmodule development well over a decade ago.\n\nThanks to @mafintosh, @andrewosh, and @feross for many long conversations about\nreadmes and Node.\n\n## See Also\n\nREADMEs love [`readme`](https://www.npmjs.com/package/readme)!\n\n## License\n\nISC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackergrrl%2Fcommon-readme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhackergrrl%2Fcommon-readme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackergrrl%2Fcommon-readme/lists"}