balderdashy/sails — pull request #1058 by yoshuawuyts (2013-11-05 13:53:37+00:00)
Title: Update README.MD

It took me quite a while to get this rewrite done. Before you continue I suggest you [preview the docs](https://github.com/yoshuawuyts/sails) to get an idea what I'm talking about. Happy reading!

Disclaimer: the format and parts of the wording are copied from the [yeoman repo](https://github.com/yeoman/yeoman).

## Rationale

### Know your crowd

Visitors can be devided into two groups.
- First timers, who recently heard about Sails and are curious what it's about.
- Frequenters, who want to find something specific.

First timers should get a clear idea of what Sails is. A concise description with an image of the architecture should do the trick. Frequenters just want to get to a relevant section as soon as possible, thus making the docs short is crucial.

The wording could use some polishing, but the general idea is to keep it concise and to the point. The less clutter there is in the README, the happier all of your users will be.

### Separation of concerns

In order to prevent conflicts between docs it's recommendable to keep documentation in a single place. The current README acts like a second docs. If you keep the docs exclusively in a seperate repo the amount of PR's opened on your main branch about docs should be greatly reduced.

### Installation

Short, simple. The next logical step after installing Sails is to run the ````sails ```` command, and from there it's straight forward.

### Faces

Because the team should have a face. My most sincere apologies if I didn't add everyone! I'd recommend only listing the core team since more than 2 rows could become a bit much.

### Codeclimate

They recently released node.js support. Now I'm not sure how good it is, but I'm pretty sure that they'll stay on top of their game. Having a shield telling you how clean your code is can't hurt... I think.

### License

It's already included in the repo, so there's no need to spell it out twice. Just added a link.

# What I couldn't/didn't change
But would love to see happen:

- Add the correct contributors, because I honestly have no idea who's part of the core team and who's not.
- Integrate [coveralls](coveralls.io), because testing is a good thing.
- A link to the changelog
- A link to the roadmap (a [Trello board](https://trello.com/b/LCDud1Nd/brackets) with upcoming features would be awesome)
- Add an overview of the architecture, much like [Polymer](http://www.polymer-project.org/images/architecture-diagram.svg) did.

p.s. The README changed from 292 to 51 lines, that should help with maintainability right?