We can easily suggest, or require, that all javascript snippets conform to standard. This can be done using https://github.com/zeke/standard-markdown.

However, this is no longer strictly about the README, which is why I think that this should be a suggestion, but not necessarily a requirement. What do you think?

Some sections (banner, badges, short description, long description) currently have a point:

• Does not require its own title.

I’m not sure if it’s intentional that people may use Banner, Badges, Short description, Long description as titles under this point. Should it be prohibited?

• Must not use its own title.

I'm not sure why I called this readme-standard. I think standard-readme is better. I know this is bikeshedding, just, thinking of changing it.

Anyone else have thoughts, while I'm at it?

In the spec, the requirements section contains the line: “Sections must have the titles listed below, unless otherwise specified“.

• Does that reference the “Extra sections” part?
• Is this the default so that the spec could later allow alternative names for sections?
• Can you use any heading, as long as you specify in the readme that it’s not compliant?

@tunnckoCore, here:

one more thing: requirement - "each section must include 'back to top' link", would be great!

Hmm I haven't seen this much! Might be cool, but also adds noise. Maybe optional?

There should be a NER or term recognition tool that automatically extracts relevant terms from the description and the background section, so you don't need to rely on things like tags in the package.json.

Now that we have generator-standard-readme, which uses a bin file and is aliased as standard-readme too, it might be smart to rename this package (but not the repo) to standard-readme-spec, which will print out the spec. Then there is no conflict with the standard-readme repo, which uses yeoman as a dependency to automatically generate readmes.

On the other hand, standard-readme should eventually be a linter, so maybe we should wait until that exists.

There should be a linter, after the spec in the main readme is filled out. The linter will most likely use remark and remark-lint. This is the planning issue for the linter. Please subscribe here, and open new issues for tangential questions about Standard Readme.

At time of writing this repository's README.md does not contain the required Maintainers section.

There are badges for licenses and there could be a linking badge to a maintainers information (link).

Since the license section is usually very short, like:

## License

MIT

It might be actually better to have as badge.

Right now Readme's in github are not internationalised. Even if they could be. I.e README.ja.md could show the readme in japanese. I think it would be a step in the right direction to specify this format as well.

What

Some people would prefer to have install at the very top, so that people can easily see it is an npm module. This conflicts with the current standard, which has it below the TOC.

Background

@feross wrote this here:

One of the best things about the npm community's readme convention is that "Install" usually appears right at the top. I like that convention because it lets users know that this is a proper npm package -- not some janky old-style JS project where you download a "standard.min.js" file or something.

I've heard folks argue that it's best to put "Install" later, after the user has learned what the package does and is actually ready to use it. But that makes it harder for users who already know what it's for does to find out the npm package name, and obscures the fact that it's a simple-to-install npm package. I think that ought to be right at the top.

I think this is a very good point. Around one third of the top 30 npm packages have install sections near the top. I like how node-redis does this: it just has 'Install with' at the top.

I want to look into this more: the issue really isn't where Install is, it's where the ToC is. Someone else has raised questions about the Table of Contents to me, and whether it is necessary. We could collapse the ToC:

Actionable items

• Talk about how to best do this here
• Go through npm modules and find justification for having a Table of Contents where it is
• Add an FAQ to the spec about where the Install section should go, and whether adding a non-header npm install package is OK.

For repos like github.com/ipfs/specs , the "Install" and "Usage" sections aren't relevant -- but the standard-readme spec requires them. This should probably be adjusted.

“Back to top” may be useful (although browsers also often supply a feature for this, on mobile you can often click the top bar to scroll up). But maybe it’s more clear if there’s an example of that, or a link to a readme that uses it?

A "[Back to Top](...)" link for longer sections can be useful, but is not required by any means.

I've seen quite a few projects where the links in the readme do not work; this is disruptive when you want to evaluate libraries or troubleshoot.

Examples:

• A link or image that 404s
• Trying to link to a non-existent file in the repo
• Syntax errors

I feel that no broken links as a rule would be valuable

A lot of repositories on GitHub do not, in fact, use code. For instance, awesome-* lists are generally just lists in a README that do not have any code to install or use. Another example are README's introducing discussion repos, where everything happens in the issues, and the README is just a placeholder telling people to go there.

In the second case, I've been using this format:

# apps

[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
[![](https://img.shields.io/badge/discussion_repo-go_to_issues-brightgreen.svg?style=flat-square)](https://github.com/ipfs/apps/issues)
[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

> Coordinating writing apps on top of ipfs, and their concerns.

This is a **discussion repo**. That means that all of the work gets done in the [issues](https://github.com/ipfs/apps/issues).

## Contribute

Feel free to join in. All welcome.

### Want to hack on IPFS?

[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)

## License

MIT

For awesome-lists, I have a similar problem. The only difference is that the header often is the NLP version of the repo name, and that it normally has a badge linking to @sindresorhus's repo, https://github.com/sindresorhus/awesome. I think this doesn't mean it can't be standardized. I propose this format for those:

# Awesome IPFS [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)

[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)

> Useful resources for using [IPFS](https://ipfs.io) and building things on top of it

_This list is for projects, tools, or pretty much any things related to IPFS that
are totally_ **awesome**_. This is for products which are already awesome - if
you have plans for cool stuff to do with IPFS, you should build it, and then
link it here. If you have an idea for an awesome thing to do with IPFS, a good
place to ask about it might be in [ipfs/apps](https://github.com/ipfs/apps) or
[ipfs/notes](https://github.com/ipfs/notes)._

## Table of Contents

* [Any topic](#any-topics)
...
* [Contribute](#contribute)
* [License](#license)

## Any topics

...

## Contribute

Please add (or remove) stuff from this list if you see anything awesome! [Open an issue](https://github.com/ipfs/awesome-ipfs/issues) or a PR.

## License

[![CC0](https://licensebuttons.net/p/zero/1.0/88x31.png)](http://creativecommons.org/publicdomain/zero/1.0/)

We can put examples in the example folder, and specify this in the spec. What do we think?

This is a catching point for a lot of people, who think that the ToC shouldn't be there for small READMEs. It doesn't have to be, but you have to read the spec to know that. Make a better example, walking through the README and salient points.

It would be really cool if the output of of standard-readme-generator was compatible with common-readme. Since common-readme doesn't impose much, the only real thing to get consistent between the two is the notion of cognitive funneling:

Start with the most general information at the top (Name, Description, Examples) and if the reader maintains interest, narrow down to specifics (API, Installation). This makes it easy for readers to "short circuit" and continue the hunt for the right module elsewhere without wasting time delving into unnecessary details.

I think standard-readme would only need a couple of tweaks, though these are of course all personal preferences that are biased toward small modules (in any ecosystem):

1. Consider making the TOC optional, only because it introduces a lot of visual interference for people scanning the readme. It can easily add an extra pageful or two if all children sections are present. If a user does opt in for one, consider maybe only showing top-level items.
2. Consider pushing Installation under API. This is on the premise that a user is unlikely to consider installing a program unless they've looked at it in some detail, which generally includes a perusal of its usage and its API.

Cool! I think everything else is pretty much compatible and fits just fine 🎉

Seems like this package does not install a binary (as the usage section implies)

Maybe it’s just me, but I really like so-called “smart” quotes over "straight" ones.

I can whip up a PR for it!

Took a overview look at js-ipfs, saw that a requirements section was missing (issue here: ipfs/js-ipfs#453) and thinking, everything based on standard-readme is missing the requirements. This should ideally be it's own section, before the installation.

Could look something like this:

Requirements

• Ubuntu / OSX
• npm [version 3 or above]
• node [version 6 or above]
• python [version 2]

## Requirements
* Ubuntu / OSX
* npm [version 3 or above]
* node [version 6 or above]
* python [version 2]

What do you think?

There should be a tool that does this on top of the standard-readme spec.

@feross:

Never been a fan of quoting the tagline. It de-emphasizes something that ought to be emphasized.

@LinusU

I too have been rubbed the wrong way with the idea that the tagline or short description should be inside a block-quote. It doesn't feel right, maybe this is an issue that should be raised upstream?

I'm not sure that it is de-emphasized. To me, it clearly separates the text from all other text. On GitHub, this looks like color and bolding - a strong statement. In text, there is the >, which points it out.

Can we think of any sensible way to judge this objectively and not make a call based on aesthetic opinion of GitHub's coloring?

This is the planning issue for the Standard Readme generator. It will most likely be based on generator-nms, a node scaffold developed by me that is based on @sindresorhus's generator-nm, using yeoman.

Please subscribe and discuss generator issues here, and open other issues for Standard Readme questions.

Hey guys,

it would be awesome to have an accepted shares counter.
What do you think?

I'm working on project to deal with maintenance of boilerplate across projects (readmes, package.json values, common tooling, etc). In the process of writing a readme parser, I think I've determined that it's impossible to determine if a single image between the title and the short description is a Banner or a Badge. Any ideas?

(It's still very early, but here's what I'm working on)

I wonder if it would be good to add, directly in the spec, reasoning for each section. This might add more extraneous content to the spec, but it might make it clearer why certain choices have been made. Thoughts?

I think a badge might seriously help adoption. I know they are not useful outside of GitHub - but to leverage the social network and make this spread, I think a badge would be more of a benefit than a detraction.

Suggestion:

These requirements are only for the IPFS organization. They are included here because some people may still be curious how IPFS and Standard-Readme are related. Since this work is supported and will be used by the IPFS organization, they are relevant here, too, I think.

• Buttons
  • All repos: irc, made by Protocol Labs, IPFS project
  • Language repos: langdoc references, code style, dependencies, coverage
  • Travis
  • CI
  • Discussion repos
• Contribute banner with link to global contribute.md
• Link to questions
• LICENSE file
• PATENTS file
• Contribute.md file

What

Some people have asked me why the Table of Contents is important. Example.

Background

I've been getting some pushback about table of contents being mandatory. For small READMEs with minimal sections, I can understand why this is a friction point. The Table of Content takes up visual space.

However, for longer READMEs, I think a Table of Contents is super important. It allows the reader to know what sections are included in the README at a glance, normally without scrolling down, unless the reading window is small (and, if it is small, a Table of Contents can help signpost whether it is worth scanning to the end or not).

I suspect that most of the time a new module is discovered, it is discovered on GitHub these days - the Table of Contents provides an easy way to navigate a README.

I think this would be great!

Roadmap

• Example Readmes
• Integrate CPAN feedback from @noffle #3
• Generator with yo as an implicit dependency. #6
• Try to merge some standard- and common-readme ideas into one readme. #10
  • Make it less js-specific #8
• Linter #5
• Use on specific IPFS Readmes, get feedback from Protocol Lab developers
• Usage tests: Get a bunch of people to use it in their projects and gather feedback on whether it's useful and how we can improve it to match real people's need.
• Press Release
  • Medium Article
  • Post on HackerNews
  • Post on Reddit
  • IPFS Newsletter (again)
  • npm weekly (they might pick this up -- they often take community modules)
• Create badge. Specify as optional.
• Plugins
  • Build Atom plugin
  • Build Sublime plugin

According to a background, this project is inspired by feross/standard. If I use standard code style and readme. Badges will be like this below:

I would like to style standard readme badge below:

What do you think ?

@tunnckoCore, here:

Except one requirement in "Table of contents":

Must be at least one-depth: must capture all ## headings.
In my repos i my name and badges/links to me as last h2 heading.

That's cool; for reference, see this README. I don't think this is the right approach, though - it's something I haven't seen much before, and I don't think it adds anything to the repo by having these be sections. So, I don't think I will adopt this. The creator's name isn't actually relevant to the code, and doesn't help with using it.

@rstacruz, here:

Curious: Would it be prudent to require a ToC even for the shortest of readmes? What led to the decision to require ToC's?

I think that ToC's make it much, much easier to get - at a glance - what is in the readme when it is long. For shorter ones, I don't think it adds too much noise, and it is still useful for simply not having to think about scrolling. A lot of people work on GitHub on small screens - my mac is a puny 5 inches high. Having a ToC helps more than it detracts. Keeping it to second-level headers only is useful. This is a style decision.

What do you prefer? opened this: https://twitter.com/richlitt/status/731291000329646081

It would be amazing to have a way to infer the impact of adopting standard-readme, to make sure that it not only improves the quality of a project, and therefore more usage, but also opens the floor for innovation (A/B testing). This will also validate standard-readme goal.

Things like nodei.co or Github Analytics will be good sources to capture and visualize the growth and infer if there is any correlation.

Some projects use external api documentation, the might be generated like go-doc or hand written like js-ipfs-api in API.md. It would be good to have some rules around how in this case the API section should look like.

I am not convinced that the README's top header 100% needs to match the name of the module perfectly.

Example: standard's README could be labelled # standard, or # Javascript Standard Style. The same follows for # standard-readme or # Standard Readme.

On the one hand, it should match what the module is named or called when you download it. However, that is why we have an install section, anyway - you shouldn't need to get this from the top title. As well, the top title should be human readable. It's the first very first thing a human looks at. Naming it for, more often than not, the overall folder or computational name - which may be slightly off what the module should be called, due to a busy ecosystem and a full namespace (the right name may have been taken already, for instance) - seems counter productive.

Is there a way we can regulate how this name should look, to make sure it is similar? Besides using human judgement, I don't think so. That having been said, human judgement is a much more powerful tool than any linter, and is what drives this standard, anyway.

The computational title should be gotten in the install section, anyway.

Hi @RichardLitt,

I was at the JS meetup yesterday in Montreal where you talked about the project, I initiated a similar approach with https://github.com/davidbgk/open-source-template/ two years ago.

Definitely not the same activity there but maybe some things to add/consider in your standard readme? Like ethics, language or financial.

Oughtn't there to be one?

In the spec, the requirements section contains the line: “Must be new lines between each section”.

I perceive that as ambiguous, is this ok? (new lines)

# standard-readme
## Install
```sh
npm install some-thing
```
## Usage
```sh
some = require('some-thing')
some.thing()
```

Or this? (blank lines)

# standard-readme

## Install
```sh
npm install some-thing
```

## Usage
```sh
some = require('some-thing')
some.thing()
```

Or? (blank lines between blocks)

# standard-readme

## Install

```sh
npm install some-thing
```

## Usage

```sh
some = require('some-thing')
some.thing()
```

Or even? (blank lines between blocks, double between sections)

# standard-readme


## Install

```sh
npm install some-thing
```


## Usage

```sh
some = require('some-thing')
some.thing()
```

...and finally: should the spec be unambiguous in this case?

Maybe it makes sense to create links for subsections, or even all the points in the spec; something like what d3 does maybe?

Also useful for a linter to link back to the spec.

For example:

# Specification

A compliant README must satisfy all the requirements listed below.

<a name="spec-requirements" href="#spec-requirements">#</a> **Requirements:**
  - <a name="file-name" href="#file-name">#</a> Be called README.md (with capitalization).
  - <a name="file-name-i18n" href="#file-name-i18n">#</a> If the project supports i18n, the file must be named accordingly: `README.de.md`, where `de` is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages.
  - ...

Yields (I don’t think it works in issues though, but it does in readme’s on GitHub):

Specification

A compliant README must satisfy all the requirements listed below.

# Requirements:

• # Be called README.md (with capitalization).
• # If the project supports i18n, the file must be named accordingly: README.de.md, where de is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages.
• ...

I added a requirement that the Contribute section should link to the Code of Conduct. Normally, this is in a separate document or in the Contribute.md, as far as I've seen before.

Should we provide suggestions?

Also, what code of conduct should we use? I know there are some standards, like the Contribute covenant http://contributor-covenant.org/version/1/3/0/.

There's a lot of js-specific stuff. would be great to use this across languages. maybe qualify suggestions with the language it applies to. same goes for package managers, etc.

@tunnckoCore, here:

And second I also don't have License section, because it 1) can be accessed directly by opening the LICENSE file from file browser, or 2) by clicking the badge which is next to the name of the repo (h1). I think it is more faster than scrolling to the end of big/small readmes. Look at mukla's or hybridify's current/latest readme using verb 0.9. :)

If you are lawyer or such, or just you come to see the license, isn't it more natural to look is there a license file first and open it directly, instead of scrolling and etc? That's why I don't have license section. Also in the package's npm page have link to license based on license field in package.json.

I still think it is industry standard - at least in the Node community - to have a License note, and as it is the last element, I don't think it detracts. The README should be the sole source of information - it can link elsewhere (like to the LICENSE file), and I think this redundancy (which you are right, it is) is useful, in that regard. If I just cat the README, I should know the License without having to look in another file. Also, package.json is js-specific. I want standard-readme to be more than just javascript.

Just found verb, might be a good way to build another generator that is less dependent on Yeoman (if needed) .

I have moved this repo to my own name from the IPFS org, because I think it will be more general than just for IPFS. My plan is to work on this and build it into something that can be used for other projects.

This will be of course based partially on zcei's standard-readme, as I finally have the time to take on the issue originally posed by @maxogden over at feross/standard in this issue.

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

Once you have installed CI on this repository, you’ll need to re-trigger Greenkeeper’s initial Pull Request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper integration’s white list on Github. You'll find this list on your repo or organiszation’s settings page, under Installed GitHub Apps.

Currently under progress.

Perl hackers have been writing great READMEs in a consistent format for ages: http://search.cpan.org/~lloydg/List-Zip-0.04/lib/List/Zip.pm

Key elements:

1. Name + Tagline: a tiny sentence that describes what the module does.
2. A "Description" section that gives people without necessary background the means to understand the module's purpose.
3. A concrete, runnable example that the user can copy locally and experiment with.
4. A Methods listing that documents the public API, complete with examples where it helps.
5. See Also: a mechanism for discovering other modules that work great with this one. (audio-lab does a great job with this throughout their audio modules)
6. Copyright / License (I'm more interested in the latter)