[Draft] Outline of README

Question

[Draft] Outline of README

zcei opened this issue 9 years ago · 34 comments

zcei commented 9 years ago

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 #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

donaldjarmstrong commented 9 years ago

+1

Answer 1 · 2015-06-03T13:51:57.000Z

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)

Answer 2 · 2015-06-03T15:02:39.000Z

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.

Answer 3 · 2015-06-03T15:17:38.000Z

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.

Answer 4 · 2015-06-03T15:43:09.000Z

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.

Answer 5 · 2015-06-03T20:35:43.000Z

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('...')

Answer 6 · 2015-06-03T20:40:23.000Z

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 👍

Answer 7 · 2015-06-03T20:49:35.000Z

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.

Answer 8 · 2015-06-03T20:54:14.000Z

@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.

Answer 9 · 2015-06-03T21:10:14.000Z

@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.

Answer 10 · 2015-06-03T21:10:42.000Z

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.

Answer 11 · 2015-06-03T21:11:06.000Z

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

Answer 12 · 2015-06-03T21:12:02.000Z

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.

Answer 13 · 2015-06-03T21:14:15.000Z

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.

Answer 14 · 2015-06-03T21:17:06.000Z

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

Answer 15 · 2015-06-03T21:17:38.000Z

I think that the @zcei's initial post is a good target for a first product, with the addition of API being made a requirement according to @mattdesl's suggestion.

license: +1 on using ## license, -1 on badge
usage before install: +0, either works for me. Maybe go with what's most commonly used initially and discuss the order further in a separate issue?
api validation: needs a separate issue to discuss syntax.
development: -1, this is not a standard requirement for modules. imo npm i and npm t suffice.
teardown: -1, because I've never seen it though I'm curious what you envision going in there.
contribution: +0, it's useful but I don't see it around a lot. Maybe it should be included? idk. Separate issue?

There are probably a bunch of optional sections (such as events) that could use some formalization, but I suggest we focus on the core sections first. As it wasn't mentioned before, I'll put it out there:
I think standard-readme should ignore sections it doesn't recognize, allowing users to add their own where they see fit.

Answer 16 · 2015-06-03T21:18:45.000Z

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.

exactly. it is the same to me for versions.

-1 for omitting the License section, just because we use a badge at top.

im not saying to restrict people to having it, lol - just to be optional and not throw if it not exists.

and some people might still want to have some short license text in the readme.

there's no reason to have license text at the readme, when you can just focus the license file on the moment when you visit the page and click on it if you want to read it. There's no sense to do needless clicks, scrolling, having "short license text at the bottom" and etc when you have what you need and it is on focus of your eyes from the moment you visit the page.

If you are in the page to search license or you are legal guy your first thing to think is to look the list of files of the repo, then package.json, then anything else - badge and bottom of the readme as last instance.

Answer 17 · 2015-06-03T21:26:15.000Z

@tunnckoCore I don't like calling people out, but with 10/23 posts on the thread I feel like you're generating a lot of noise. Can you please consolidate your comments to keep the conversation focused? Thanks!

Answer 18 · 2015-06-03T21:27:56.000Z

Okay:

badges: for the sake of text-editor readability they are completely optional. If they're used, it's directly under the title
license: there is a License section at the very bottom, optional is linking to a LICENSE file
installation: before usage, for what I've seen it's commonly used
usage: if CLI it's the most common call to it
api: required block, outline/validation in #3, if CLI here are all flags described

Other optional blocks can be proposed afterwards - I want to have a base consensus first!

Can everyone agree to this?

Answer 19 · 2015-06-03T21:28:07.000Z

As it wasn't mentioned before, I'll put it out there:
I think standard-readme should ignore sections it doesn't recognize, allowing users to add their own where they see fit.

👍

I feel like you're generating a lot of noise.

Oh my god... noise. We commenting, we are here to discuss.

Answer 20 · 2015-06-03T21:30:36.000Z

I'm thinking about images or gifs to show an application usage, as this example.

Answer 21 · 2015-06-03T21:33:00.000Z

@RodrigoEspinosa: actually it's at the same syntactical position as the badges would be :D So there is no problem in having them there.

Answer 22 · 2015-06-03T21:34:49.000Z

@zcei that's ok then, I'm totally up for this standard 🐎

Answer 23 · 2015-06-03T21:35:13.000Z

@zcei

usage: if CLI it's the most common call to it

I assume it'll be called usage regardless if it's a cli, right?

Answer 24 · 2015-06-03T21:37:23.000Z

@yoshuawuyts sure :)

Answer 25 · 2015-06-03T21:38:14.000Z

I'm thinking about images or gifs to show an application usage, as this example.

I love when see it somewhere, but there's some modules/repos/libs/projects/packages that cant be displayed as gifs.
That's why @yoshuawuyts is right, we should concentrate on the core.

Can everyone agree to this?

yep, except required license heading (block/section).

Answer 26 · 2015-06-03T21:38:37.000Z

@zcei Cool, +1 on the proposal.

edit: maybe update the opening post to reflect the latest proposal?

Answer 27 · 2015-06-03T21:55:01.000Z

@yoshuawuyts did so.

Good work all 👍

Will look into the markdown linting stuff tomorrow. Someone already started this? Let me know in case you want collaborator access

Answer 28 · 2015-06-03T21:58:17.000Z

@zcei Neat!

I've done markdown parsing with marked in mdjson, it might serve as a good reference implementation. Someone suggested using mdast in another thread though, it definitely looks worth checking out.

Answer 29 · 2015-06-03T23:20:21.000Z

Here's what @writethedocs has to say about the rough "what to write" outline of a readme http://docs.writethedocs.org/writing/beginners-guide-to-docs/#what-to-write

Answer 30 · 2015-06-04T06:05:48.000Z

I really think mdast to be a good markdown listing tool. Then again, I'm the author ;)

in my defence, mdast has a lot of features, such as a warning interface built-in, which will require less boilerplate for a markdown/readme validator.

Regarding linting itself, I'm almost done with a markdown validator. which does similar things to standard-readme, but focuses more on syntax and less on semantics.

It's currently a private repo but I'd be glad to add anyone who wants to take a peek as a collaborator.

Answer 31 · 2015-06-05T16:02:14.000Z

@wooorm For sure I'd like to have a look at it. I'm sure it will help a lot!

Also it's nice to have the owner of the used lib involved in the discussion here, so I'll give mdast a try.
Weather will be awesome here, but I try to get a first draft this weekend. Stay tuned!

Answer 32 · 2015-06-06T16:34:50.000Z

Documentation section, links to reference manuals (internal, external or wiki etc)

Answer 33 · 2015-06-12T11:58:00.000Z

Wanted to post a little update:

Together with @wooorm s superb mdast-lint I'll try to build it as an external rule.
A bit like standard is doing with eslint.

I opened a ticket and hope to get my hands dirty this evening, as I'm having a little pre-battlehack sit-in which hopefully results in hacking.