idea: standard-readme

[max-mapper]

I use standard to check my code, dependency-check to check my package.json deps are sane, but I don't have anything to check my readme.

I wonder if it would practical to do for node module readmes what standard did for JS style. There is a pretty cool markdown linter called markdownlint that could be used for basic style checking.

Going beyond style, though, what about failing if these cases are not met:

• readme must have a title
• title must be followed by a description
• description must be followed by a nodei.co badge
• readme must have a section titled installation
• readme must have a section titled example or usage
• readme must have a section titled api
• api section must have a sub section for each public method in the modules main entry
• readme must have a section titled license

so, does this seem like a good idea? what are other base requirements that should be added (or removed) from the above list?

[RichardLitt]

I like the idea.

I would also add a check for contributing.md. contribute.md had an idea for making a standard one, but seem to have abandoned it in the past year. jden/contribute.md is another repository trying to figure this out. Since Contribute is normally a separate file, though, this might be suited for a different linter.

[yoshuawuyts]

+1 on the idea; the list of headings seems about right to me. I also like to include a See Also section for related modules / prior work to help with discovery; not sure if it would make sense for every project though.

The only point I'd argue for a possible alternative is the use of nodei.co, I don't find the badges to be very pretty. Alternatively shields.io badges could be used. E.g.

Somewhat relevant: there's a chrome extension for nodei badges on every repo.

[dcousens]

I like the idea of this.

readme must have a section titled api

This will definitely limit the ability for large projects to use standard, since they typically don't have all their documentation in the README.

api section must have a sub section for each public method in the modules main entry

And what if the entire API is outlined in a the examples section? Sometimes I think the extra documentation could be excessive.

[sergiolepore]

+1 readme
+1 contribute
+1 shields.io badges

😁

[yoshuawuyts]

Coming back on my previous comment, I don't think the see also section should be required. As I missed in the initial post: the key word is base requirement. I agree that installation, usage, api, license is the bare minimum a project should have; nothing to be added / removed from that list imo.

Sometimes I think the extra documentation could be excessive.

It can be as little as a line per api method. Having an api section makes it a lot easier to just look up something no matter how small the project (and know what types it takes, etc.) Take a look at yoshuawuyts/simple-store to see an example.

This will definitely limit the ability for large projects to use standard

What are the alternatives? I'd argue that dedicated documentation sites / wikis are less clear than a single file with all the methods described. Take a look at browserify to see an example.

[max-mapper]

This will definitely limit the ability for large projects to use standard

re @yoshuawuyts @dcousens

I guess the spectrum is:

• On one side you have no code/api docs in the readme.
• In the middle you have a list of public methods in the readme, or you have code examples in the readme.
• On the other side you have automated tools that can parse your code examples/API docs and prove that you have 100% code coverage between your documentation and the code in your repo.

Obviously we want some checking here. But we also want it to be as simple as possible, with a focus on only testing things that are essential. I also don't want to require people to use a special JSDoc style inline code documentation tool. You can use one of these if you want, but you should also be able to simply hand write the docs in the readme. The standard-readme would just check whatever readme gets generated.

Generally my motivations here come from that I maintain ~300 node modules and want to ensure a base level of quality across them all.

also @yoshuawuyts the utf8 in your name is super annoying to me btw :), e.g.:

[jprichardson]

@maxogden Just so I'm clear, you're suggesting a new module for standard-readme that is separate from standard? I mean, even different from standard-format in the sense that you're not suggesting standard to depend upon standard-readme, right?

[max-mapper]

@jprichardson yes this thread is a discussion on a completely separate cli tool

[dcousens]

What are the alternatives? I'd argue that dedicated documentation sites / wikis are less clear than a single file with all the methods described

I completely agree with you, if the documentation is too much to fit in the README, its probably not modular enough IMHO; but that is separate to the discussion of whether we should bar projects from being able to use it just because they aren't modular enough.

[yoshuawuyts]

@maxogden (: alright then

[tunnckoCore]

I can argue with some of the points. And they are

description must be followed by a nodei.co badge

it is weird to force this, @yoshuawuyts shared cool extension for it, thanks. nothing that it isn't exactly as in the preview from the chrome store, lol.

readme must have a section titled installation

maybe if it allow install or installation, then okey. cuz all of my modules are with Install section

readme must have a section titled example or usage
readme must have a section titled api

I'm not against to have some brief short api documentation in readme, but sometimes I have just API without usage, cuz below it i have description of the constructor, params and etc and below it i have bold "Example" section with short example.

Some refs tunnckoCore/npm-related, hybridables/hybridify-all and hybridables/hybridify.
In hybridify-all you can see my latest readme style which I'm forcing through my repos last weeks.
In hybridify can see more expanded readme with more examples

It is short and pretty cool, cuz

1. have badges for all
2. have correct h1 heading
3. have badge for the license with link to the license file
4. have related section (I can change it to See also, which yea, make more sense sometimes)
   • which is generated from npm-related
5. have contributing section with brief info and link to the CONTRIBUTING.md file
6. have some links and badges for me, the author
7. have some basic Usage and API per method
   • which also is generated from code comments, like here tunnckoCore/is-kindof
8. actual and good shields.io badge for the npm version of the package, not ugly always-green-no-matter-what-is-your-package-version fury badge.

readme must have a section titled license

Not needed, really. It is better to just have on top some badge which contain license identifier (because the SPDX, applied from [email protected]+) and to be link to the license file containing full license text and copyright holder(s). It will look more standard, instead to have "MIT" / "License" / "MIT LiCeNSe" or whatever section at the bottom.

I also will start updating my package.json to be more compact. e.g.

{
  "name": "foobar",
  "version": "0.1.0",
  "description": "brief info about foobar",
  "main": "index.js",
  "license": "MIT", 
  "author": "Charlike Mike Reagent <@tunnckoCore> (http://www.tunnckocore.tk)",
  "repository": "tunnckoCore/foobar",
  "scripts": {
    "test": "standard && node test.js"
  },
  "dependencies": {},
  "devDependencies": {
    "assertit": "^0.1.0"
  },
  "keywords": []
}

which also is so clean and cool it hurts.

standard, istanbul and coveralls are handled by travis.yml file

sudo: false
language: "node_js"
node_js:
  - "0.10"
  - "0.12"
  - "iojs"
before_script:
  - npm install standard
  - standard
script:
  - npm install istanbul
  - istanbul cover test.js --report lcovonly
after_script:
  - npm install coveralls
  - cat ./coverage/lcov.info | coveralls

It is like that to speedup the local developing process with just verifying that everything is standard before push to git. Plus cool notice in CONTRIBUTING.md to use and install standard globally before PR - that is the only requirement to do PR. It is weird and cost developing time and bandwidth to download these big pkgs like coveralls, istanbul and standard everytime for single PR or commit (cuz I dont have all my ~200 pkgs locally - its weird. I just tunnckoCore/gitclone them, do the changes publish/release them, then delete the folder), when you can (and it is 90% guarantee) you have them installed globally and you use them in daily basis.

Regards,
Charlike! 🐈

[shama]

mdast is a great tool if you wanted to write your own linter.

[mattdesl]

My 2c...

description must be followed by a nodei.co badge

This seems like a bit of vendor lock-in.

readme must have a section titled installation

To me this seems like cruft. The majority of people already know how to npm install --save and it's just another paragraph that we (module consumers) have to scroll through to get to the meat of things. If necessary, I think it should go after the code example (since the example is what I'm looking for 99% of the time).

readme must have a section titled example or usage

The header makes it easier for the linter, but it's also cruft IMHO since it's pretty clean and obvious when the example code is listed after the description. Example.

readme must have a section titled api

I've called this "Usage" since some modules are API-only, others are CLI-only, and others contain both. Example.

[max-mapper]

@mattdesl I actually very strongly disagree with The majority of people already know how to npm install --save, I see docs all the time make assumptions about base reader knowledge for things like that and it can very quickly make a learning curve way steeper than it needs to be for a newbie.

[chrisdickinson]

I usually structure my readmes as

1. one sentence description, no badges because I am horribly lazy (and I don't see a huge amount of value in them relative to their upkeep, personally)
2. example of primary usage
3. longer, 3-4 sentence explaining the package, the reason behind it, etc.
4. api
5. license

I'd definitely consider adding installation, but I would probably put it between "api" and "long description" – the first 3 points are there to let folks determine whether or not they even want this thing, and worrying about how to get it is a secondary concern to whether the thing does what they want.

[tunnckoCore]

agreed with @maxogden

it looks weird to start directly with some code snippet just after description, without any heading before it.

@mattdesl

have to scroll

it is just one-liner maximum two-liner (in my case), lol it isn't so much scrolling.

[mattdesl]

it is just one-liner maximum two-liner (in my case), lol it isn't so much scrolling.

If somebody doesn't know how to install a module, a one/two-liner probably won't make them magically understand the process of setting up node/npm/etc, much less actually using the code in an server/browser application. It gets pretty complicated.

And once you do know how to install a module, you will never need to read that section again, so it just becomes fluff that you always need to scroll by.

Some places where the installation instructions should be highlighted to stand out: modules that are mainly intended for global installation, or modules that peer-depend on something else.

Anyways... Hope this doesn't come off negatively. I am not against installation instructions, it's just frustrating that I have to scroll through all sorts of cruft just to see a code example, which is usually what I came to see.

Sorry to single your module out but here's a quick example of what I mean:

[max-mapper]

@mattdesl if I had to choose between making my readme have less content in it and be more opaque to newbies vs having more content in it and being more newbie friendly but making experienced people use a table of contents or their mouse scroll wheel I would choose the former every time :)

[max-mapper]

sorry meant the latter, hahaha

[morganherlocker]

FWIW, the Turf project uses JSDoc (and some other metadata sources like the package.json) + dox + doxme, which works well for getting the metadata into various formats (including markdown).

JSDocs like this turns into a readme & HTML from the same, easily validated source. We switched to this after updating and synchronizing nearly 100 readme files for the project was becoming untenable. I would definitely recommend a validation mechanism that is decoupled from format or style if possible.

[mattdesl]

f I had to choose between making my readme have less content in it and be more opaque to newbies vs having more content in it and being more newbie friendly

Sure, but does a one or two line "npm install -g" really help newbies? The only people who know what this means have probably already installed and used modules on a project. A real installation guide should cover installing Node/npm, updating to the latest versions, handling permissions for global installs, etc.

[tunnckoCore]

@mattdesl you have some right, i can agree. But it is like a standard in the community. You can see that in 99% of the repos/libs, so it would be expected to be part of the standard-readme and be at the top.

Sorry to single your module out but here's a quick example of what I mean:

yea, no problem. the pic show something strange in npmjs.com's parsing. I guess it checks if h1 is same as the module name. no matter, express/koa-better-body and ratelimit isn't for comparing, im working on next releases and forcing readme style like in npm.im/hybridify (see it looks better)

[max-mapper]

Sure, but does a one or two line "npm install -g" really help newbies?

I have a lot of personal evidence to support this, but no citation :)

[tunnckoCore]

I love that when I open some of my new formated repos, I can see all that I need - green light all across the services. Furthermore i have github-hide-files extension, which is absolutely cool.

[wooorm]

Thanks @shama for the shout-out. I certainly think mdast could help, for an example with eslint, check out eslint-md, which could easily be ported to standard.

However, that lints the JavaScript in markdown, not the markdown itself. TBH, is a project named “JavaScript Standard Style” the right place to validate markdown/readme style?

[tunnckoCore]

TBH, is a project named “JavaScript Standard Style” the right place to validate markdown/readme style?

it would be standard-readme for "READMEs Standard Style"

[wooorm]

Ah didn't get that, yeah that would be cool!

[wooorm]

Alright, I just created a tiny example of how mdast could help with linting markdown.
@maxogden I took your first “rule”, read must have a title, and implemented it as a simple mdast plugin over at mdast-standard-example:

git clone [email protected]:wooorm/mdast-standard-example.git
cd mdast-standard-example
npm install
node_modules/.bin/mdast . --use ./index.js

will show lint warnings:

[yoshuawuyts]

Something that this module could additionally do is lint the way interfaces are defined in the API section. Everyone seems to do it differently, and having some consistency would be great. Just to display some of the flavors:

browserify

b.plugin(plugin, opts)

Register a plugin with opts. Plugins can be a string module name or a
function the same as transforms.

plugin(b, opts) is called with the browserify instance b.

For more information, consult the plugins section below.

virtual-dom

Patch operations

patch(rootNode:DOMNode, patches:PatchObject) -> DOMNode newRootNode

Once we have computed the set of patches required to apply to the DOM, we need a function that can apply those patches. This is provided by the patch function. Given a DOM root node and a set of DOM patches, the patch function will update the DOM. After applying the patches to the DOM, the DOM should look like the new VTree.

from2

stream = from2.obj([opts], read)

Shorthand for from2({ objectMode: true }, read).

[junosuarez]

Just a suggestion: this thread has a ton of great ideas; clearly there's interest in this, but none of it is directly related to standard. Someone should create a repo and a readme summarizing what's been discussed, and further discussion should happen in that repo's issues.

[zcei]

Followed @jden's suggestion after no one else did ;)

Just dropped my thoughts about it into the README and opened an issue to further outline the standard.

@yoshuawuyts I'm also for a unified API write style. Will investigate the most common styles and an approach to melt it into smth sane.

You are all more than welcome to further contribute to it, I'll do my very best to keep the project structured & aligned with the intentions of you all!

(@tunnckoCore: I liked many parts of your proposed readmes and thus copied a bit over for the example one)

[wooorm]

Should we close this issue here as we have a place to follow-up on this?

[junosuarez]

Yes, there is active discussion happening on the standard-readme repo and this issue should be closed.

[RichardLitt]

Hey everyone: I've written a spec for standard-readme and a generator. Would love feedback and adoption:

https://github.com/RichardLitt/standard-readme

[tunnckoCore]

@RichardLitt yea, looks great to me. 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 - first. 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.

Can suggest you to add link to markdown-toc in the suggestion of Table of Contents.

@jonschlinkert, we can make verb-readme-generator spec compliant? And then if it is spec compliant @RichardLitt can add it and verb >=0.9 to the suggestion for generating the spec-compliant readmes. Also maybe create the standard-readme generator to use verb.

[jonschlinkert]

hey thanks for the mention. I'd prefer to wait until we release a stable version of verb before it enters any discussions, since it's 100% on dev brach atm. but I do appreciate it!

[rstacruz]

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

On Fri, May 27, 2016, 3:36 AM Charlike Mike Reagent <
[email protected]> wrote:

@RichardLitt https://github.com/RichardLitt yea, looks great to me.
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 - first.
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.

If you are lawyer or such, or just you come to see the license, isn't it
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.

Can suggest you to add link to markdown-toc
https://github.com/jonschlinkert/markdown-toc in the suggestion of Table
of Contents.

@jonschlinkert https://github.com/jonschlinkert, we can make
verb-readme-generator https://github.com/verbose/verb-readme-generator
spec compliant? And then if it is spec compliant @RichardLitt
https://github.com/RichardLitt can add it and verb >=0.9
https://github.com/verbose/verb/tree/dev to the suggestion for
generating the spec-compliant readmes.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#141 (comment)

[junosuarez]

@RichardLitt nice work!

Everyone: maybe we could continue feedback as issues on https://github.com/RichardLitt/standard-readme instead of in this thread

[tunnckoCore]

@rstacruz consistency maybe, and easy navigation.
@RichardLitt one more thing: requirement - "each section must include 'back to top' link", would be great!

[RichardLitt]

Thanks, @jden. Move discussion there - I just wanted to drop this here to notify participants.

Table of Contents discussion: RichardLitt/standard-readme#15
License discussion: RichardLitt/standard-readme#14
Back to top link: RichardLitt/standard-readme#16

[rstacruz]

Lateral discussion: I'm actually more interested in standardizing changelogs. It has way too many variations. (I happen to love the format I use, though, haha.) Anyone else care to have these standardized?

[tunnckoCore]

Anyone else care to have these standardized?

yea, working on it locally from time to time. Also last year I created @standards org to get them all in one place, but don't have time, currently.

@rstacruz there's already have keep-a-changelog convention, try to follow it. :D

[balupton]

https://github.com/bevry/projectz has been around for a few years now and seems to already accomplish what this issue aims to do. It is used on all bevry and docpad repos. Plan is to extend it with a plugin system in the coming months. Happy to improve it as necessary.

[cdaringe]

no shortage of solutions, I suppose, but I will also have a solution to this problem shortly via: https://github.com/cdaringe/counsel

[feross]

BTW, this is probably relevant to folks in this thread. @zeke released the excellent standard-markdown a while ago. It ensures that JavaScript code examples in your markdown files are valid standard style. Really useful.