[Draft] Outline of README

[zcei]

Updated: Wed Jun 03 2015 23:50:34 GMT+0200 (CEST) (1433368234571)

standard-readme

Constraints

• A README consists of blocks
• Blocks can be nested
• A block is made up by:
  • Rules defining the look and behavior
  • Required information
  • Predefined space for optional sub-blocks

Blocks

Heading

• requires a title
• (optional) Block: Badges
• followed by description

Install(ation)

• Even if it's just npm install <my-package>, cuz sometimes it's not
• Sytem dependencies (like ffmpeg) are mentioned here

Usage / Example

• A minimal example
• Should use / show most default values
• Shows how the developers intend the usage
• If CLI, use the most common flags in your call

API

• Like @yoshuawuyts I'm for defining a standard way to outline your API in the README
• Discussion in api section syntax #3
• If CLI, describe all your flags here

License

• Is strictly mandatory (until further reviewed by lawyer/responsible persons)
• (optional) link to LICENSE file

Optional Blocks

Badges

• http://shields.io/
• No constraints regarding flat, rounded, etc..
• Can also include images / gifs showing the projects' behavior

[joeybaker]

I'd add a required block about how to develop

Developing

• shows how run any common development tools (even if it's just git clone && npm i
• shows how to run tests (sometimes it's more complex than npm test)

[tunnckoCore]

required block

It would be better to be optional block. git clone && npm i is trivial and is no need. For example I set npm test in the install block right after the npm i pkgname command.

And vote License to be moved to "optional blocks", cuz it looks weird to have:

## License
MIT

And because it is pretty simple thing like license - mit it make more sense to be badge. Furthermore now when npm applied SPDX identifiers.

[mattdesl]

Having a License at the bottom is pretty important. We are constantly dealing with legal issues -- big companies are still not very comfortable with the idea of hundreds of constantly shifting modules, any of which might have a potentially damaging license. The more visible the license is to non-technical people, the better.

How about Example before Install? I feel like most people only install a module once they've determined it suits their needs (i.e. looked at an example).

I also feel like API documentation should be required. In my readmes I just call it "Usage" and have sub-headers for API or CLI (or both) depending on the module.

[zcei]

I don't see the point in having Development / Developing a requirement.

The repetition for Installationis justified in my eyes, as sometimes it's not clear whether to install it globally, or you just want to c&p it out from there.
(Hmm, would be quite a nice Chrome Plugin: Button next to install line to copy to clipboard)

But if you want to do further development, it often is just plain coding (git clone && npm i), without any differences like global or not.

As soon as it requires some more work than this, it obviously should be mentioned.

Development

• How to get it running
• What are you most likely to change (e.g. "everything important is in lib/" or "you are not supposed to touch anything within core/"
• How to test

Contribution

• How to make your changes project compliant
• Style conventions (incl. naming)
• How to present to project team (branch naming, branch to compare against, etc)

API as a requirement is okay for me, as long as CLI options are also mentioned in this block (especially for projects without any real API to code against)

As @mattdesl mentioned: for legal issues it's good to have it in the readme, but I fancy the idea of linking it in the Badges block. @tunnckoCore
Shields.io is from the community, so for me making them mandatory isn't a real "vendor lock", wdyt?

Then the constraint is to have a badge linking to LICENSE file, or a block at the bottom of readme.

[ungoldman]

I think a required short description (one sentence, < 50 chars if possible, like package.json description field) and optional long description (more detail, context, links as necessary, preferably 1-2 paragraphs max) would make sense. It's nice to get a decent explanation of what the package does beyond a very terse description towards the top of a README.md.

---

package-name

Short description.

Long description latte disrupt sticky note long shadow actionable insight big data pivot pair programming venture capital integrate SpaceTeam thinker-maker-doer. Minimum viable product engaging long shadow intuitive minimum viable product venture capital 360 campaign agile personas disrupt.

Install

npm install this

Usage

var etc = require('you-get-it')
etc('...')

[tunnckoCore]

The more visible the license is to non-technical people, the better.

it would be in the most visible place of the repo page, lol - next to the name of the repo, in first line of the readme. For me it enough visible and noticeable, plus it is link to license file with more expanded license text. There's absolutely no difference between to be at the bottom as heading and simple word "MIT" - whole new heading for one word and no link? nah. And why at the bottom? You're forced to scroll whole page to see the two words "LICENSE MIT"? nah, not make sense for me.
If it is so important it is better to be at the front of the battleground (at the top of readme) and in most visible place of the page.

but I fancy the idea of linking it in the Badges block

I thought that when i thinking the style of my new repos style, but didn't like the idea to have whole new section and adding more pixels before the actual reason that users is on that page - usage, example, api etc. So yea, I calculate that I should place only most most important at heading like badges for version and license, then the badges for services - which must be maximum 5 to not continue to next line.

Hmm, would be quite a nice Chrome Plugin: Button next to install line to copy to clipboard

cool idea 👍

And one more thing. The npm's step to apply standardized SPDX identifiers is cool and we should follow that step. And because license identifiers is standardized they are the best candidate for badges.

@ngoldman 👍

[mattdesl]

it would be in the most visible place of the repo page, lol - next to the name of the repo, in first line of the readme.

Well, a couple issues:

• it's placed next to a bunch of technical badges like build status, npm downloads, etc. which a non-technical person would probably not understand and/or glance over
• it's not clear you can click it to open the LICENSE.md file
• it's already pretty standard to put License at the bottom, so legal already know to look there

I think it would be best to ask a few legal people (non-technical) and get their take on it, since they are the ones reviewing and clearing libraries.

[ungoldman]

@mattdesl++ ## License\n\n[LICENSE-TYPE](link-to-license-file) at the bottom of the file is definitely a broadly used standard that I expect to see in a good readme. I don't think it makes sense to replace that with a badge.

[zcei]

@ngoldman isn't this the repository short description?

@tunnckoCore I'm up for having a required license & version badge. Not quite sure about the version though. It's commonly handled by the Releases section, but still nice to have a direct look at it.
Definitely license badge at first.

Second optional line for services as you call them totally makes sense, as they differ a lot, no assumptions should be taken here.
This should also avoid confusing non-techies, the standard is then to look at the top two badges telling you whether the lib is in a legal context that you can use it, and mature enough for you.

There should be an option to have both in the same line, that's why license is always first. (Also for a cleaner look)

-1 for omitting the License section, just because we use a badge at top.
It's just for a first glance, and some people might still want to have some short license text in the readme.
It's at the very bottom of the file, so it won't hurt anyone.
I'm more for avoiding possible legal issues (for sure it wasn't put in there for sake of putting it in)
@mattdesl let's see if we find some ;)

LICENSE file should be at the same directory level as README.md and the existence should be checked, if a badge (or ## License\n\n[LICENSE-TYPE](link-to-license-file)) links to it.

[tunnckoCore]

next to a bunch of technical badges like build status, npm downloads, etc.

it won't be there, dont look me that I set there next to license badge the npm badge - i have some habits and sense for colors and love symmetric.

which a non-technical person would probably not understand and/or glance over

why? it is same text but as image, there's no matter.

[zcei]

Other point of view:
The readme should be readable without GitHub, thus we shouldn't rely on badges at all.

[tunnckoCore]

The readme should be readable without GitHub, thus we shouldn't rely on badges at all.

agreed.

I'm up for having a required license & version badge.

Im for that they both be optional.

it's not clear you can click it to open the LICENSE.md file

it is link at the listing files of the repo lol, and for that these files are uppercased and always at the top of the list.

[zcei]

The more I think about it, the more I agree with my last comment.
It definitely should be optional, just the position is defined if there are badges.

[mattdesl]

ping @kemitchell since he may have some thoughts on how some of the legal / non-technical folk might want to see a "license" field.