Standardize Readme

[RichardLitt]

This is the most minimal change to standardize the README, following RichardLitt/standard-readme. See #558 for more on this.

Big changes: Move the title and the badges, take away the centering. This is a bit less pretty, but you should not have to think about this stuff, and standardizing will remove some aesthetic decisions, sadly. I also added a contribute, a Table of Contents, and moved badges into usage - I think this is the best move. Linked to the license. What do you think?

[feross]

I think all the changes are generally improvements, except for the changes to the title.

I understand the desire to have the package title at the very top:

# standard

But after that, I'd prefer to keep the current formatting.

[RichardLitt]

Thanks for reviewing this!

Can you be a bit more explicit about what you like about your current formatting that I remove? Is it just the centered-ness? I think that the badges and the hexagaon can be centered - I don't see any reason for them not to be.

Having "Javascript Standard Style" in a quote is the standard I see for quoting the GitHub tagline. What could do easily is this:

<p align="center">
  <a href="http://standardjs.com"><img src="https://cdn.rawgit.com/feross/standard/master/sticker.svg" alt="JavaScript Style Guide - JavaScript Standard Style" width="200"></a>
  <br />
  <a href="https://travis-ci.org/feross/standard"><img src="https://travis-ci.org/feross/standard.svg?branch=master" alt="Travis"></a>
  <a href="https://www.npmjs.com/package/standard"><img src="https://img.shields.io/npm/dm/standard.svg" alt="npm downloads"></a>
  <a href="https://www.npmjs.com/package/standard"><img src="https://img.shields.io/npm/v/standard.svg" alt="npm version"></a>
  [![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
</p>

> JavaScript Standard Style

If you're really keen on having "One style to rule them all", we could add that to the GitHub description, too. That way it could be in the quote. Or, just add it to the description underneath "it just works". It doesn't really add much, as it is, although I do like the Tolkien reference.

[feross]

Basically, I think the title section was near-perfect before and this PR makes it worse. Never been a fan of quoting the tagline. It de-emphasizes something that ought to be emphasized. And the large "JavaScript Standard Style" heading looked great too.

[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?

[rstacruz]

Personally I actually feel like the blockquote makes it stand out more (i never actually noticed it before seeing this), but that's just my opinion

[rstacruz]

I do feel strange that "Rules" is above "Install" though.

And "badge" seems weird that it's under "Usage", an in fact above "text editor plugins" (docs that are easily 10x more useful).

FWIW though, i think the TOC helps.

[feross]

The irony of us debating the merits of each rule in a "take-it-or-leave-it" standard is not lost on me.

@RichardLitt To get the uncontroversial parts of this PR merged, what do you think about just undoing all the changes to the title section? We can work out what to do about the title in another PR.

[feross]

@rstacruz That's a good point too.

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.

[rstacruz]

Also, I do wish "hero images" are part of standard-readme somehow.

I feel this makes MUCH more sense in terms of image placement. Many projects with logos do the same thing.

[RichardLitt]

Basically, I think the title section was near-perfect before and this PR makes it worse. Never been a fan of quoting the tagline. It de-emphasizes something that ought to be emphasized. And the large "JavaScript Standard Style" heading looked great too.

I agree that it looked good before. I'm not sure it was maximally functional, though. The "One style to rule them all" didn't add much. I think that "Standard JavaScript Style" is more informative than "standard" - but it's not at the top, which would be useful for parsing.

How do you feel about @rstacruz's suggestion of having the badge above, then "standard", then the badges? I think that would be a good compromise.

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?

Good call! Let's talk about this, here: RichardLitt/standard-readme#22

I do feel strange that "Rules" is above "Install" though.

I wanted the rules to be somewhere; they could be in a ## Background section, which is meant for long description. I would need a bit more description, though, I think, as:

## Background

### Rules

Looks a bit weird. Personally, I would put them after Install and after Usage, because that is where I think they belong - they are references. This would fit standard-readme much better! @feross, thoughts on this?

And "badge" seems weird that it's under "Usage", an in fact above "text editor plugins" (docs that are easily 10x more useful).

Could be below. Probably a good idea. I just think it didn't need to be in the Description, as it's not all that important to using the module. We could add it in Background, too.

FWIW though, i think the TOC helps.

Sweet.

The irony of us debating the merits of each rule in a "take-it-or-leave-it" standard is not lost on me.

Well, my standard is fairly new! So this is 100% OK.

[feross]

I think that "Standard JavaScript Style" is more informative than "standard" - but it's not at the top, which would be useful for parsing.

👍

How do you feel about @rstacruz's suggestion of having the badge above, then "standard", then the badges? I think that would be a good compromise.

I think that would work.

Personally, I would put them ("Rules") after Install and after Usage, because that is where I think they belong - they are references

I think for a style guide, this section is pretty important. They should probably appear in the top description section, or at the top of the Usage section.

[feross]

It sounds like we got everything agreed upon -- want to just update this PR and scratch the other one you opened without the title changes? #578

[RichardLitt]

We're almost there!

So, I think you're right that the hero can be above the title, and centered. I don't see a problem with that. I'll update the spec accordingly.

I also think that the badge shouldn't have to be flat or square - as long as it is there, it works. I've kept Rules up top, which works fine. They could be between Usage and FAQ, but I agree that they are important.

Regarding moving install above: I don't think that this is the best idea. It's its own section, and I think that moving it wouldn't actually benefit anyone - on GitHub you can click install to skip the ToC, and if you have it downloaded you likely already know it is an npm module. I've also gone through and separated out a section from Usage which should be in the install section - for standard to be installed as a CLI, which I think may be a more common use case, and should be in Install, anyway.

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 agree with this. But you already have two npm badges at the top, and we have it before usage, anyway. I don't think everyone who comes to the README wants to know how to install, either - sometimes, they're looking at the rules again, or the FAQ, or how to contribute. I think that Install can be directly beneath the ToC. Do you see my reasoning, here?

[feross]

Can you make this say "JavaScript Standard Style" ?

[feross]

I don't agree with the reasoning about "Install" because basically every npm package puts it at the top of the readme, and I think that it's worth preserving that convention. But it's fine -- we can try it out your way for a while.

I left more comments inline. Once those are fixed up, we can merge this.

[RichardLitt]

Install Section at the top

I went through the top 30 packages on npm; around a third of them have install sections near the top. I like how node-redis does this: is just has 'Install with' at the top.

I've added that here. I like this a lot: it isn't intrusive, it shows how to install it where you want it (above the rules, even), and there is a more detailed install section below. What do you think?

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:

_the rules section_...

## Table of Contents

- [Install](#install)
- [Usage](#usage)
- [FAQ](#faq)
- [Node.js API](#nodejs-api)
- [IRC channel](#irc-channel)
- [License](#license)

## Install

I opened an issue here to look into this issue, further: RichardLitt/standard-readme#25. For now - how do you feel about what I've just pushed, with a redis-like short install section above the TOC?

Thank you so much for being so responsive, really. It's great to see how much thought you're putting into this.

H1 Naming

You want to rename # standard to # JavaScript Standard Style. I completely understand why you would want this. I've opened this issue to talk about this. I don't see an issue with having JavaScript Standard Style, but it will change the specification, so I want to make sure we discuss that. Want to respond to my post there (is that ok?) so we don't dirty up this issue more than it has to be?

[RichardLitt]

Thanks, @feross!

[Flet]

I bumped http://standardjs.com to use this and it looks good except for the quoted text at the top (IMO) :)

Take a look?

[Flet]

Not a huge deal btw, maybe just adding some style will make it nice.

[RichardLitt]

@Flet Let me know where to add style: I can do it?