Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Update README.MD #1058
EDIT: Click to see the new docs, they are nice.
It took me quite a while to get this rewrite done. Before you continue I suggest you preview the docs 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.
Know your crowd
Visitors can be devided into two groups.
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.
Short, simple. The next logical step after installing Sails is to run the
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.
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.
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:
p.s. The README changed from 292 to 51 lines, that should help with maintainability right?
Love it man, especially the contributors section-- obviously this one needs to stay on
some other stuff that might help out with the rest of the bullet points you identified:
In general, features can be grouped into three categories: (1) stuff in core (2) increased unit test coverage and (3) adapters/generators/grunt contributions. The easiest place for most folks to get started is the third camp, so I want to try and make it easier for a new contributor to see where they can get involved.
@mikermcneil Good to hear you like it.
I know you've been very busy, but I feel I need to share this. As much as I've enjoyed Sails in the past, right now I feel very disconnected from it. For me the amount of outdated documentation, piling issues on the tracker and unclear direction make it hard to keep investing into Sails. The prolonged absence of core members like yourself and delayed responses on most issues make it hard to keep investing. If you want to lead Sails forward, I urge you to invest in clarity.
Right now what I think should happen is:
And as a final addition I think creating a visual representation of the project architecture could clear up the project even further.
I don't think you should prioritize getting new contributors in, I think they'll come naturally once the points above have been addressed.
@yoshuawuyts Good ideas, thanks! When 0.10 is released, a lot of what's been going on should make more sense-- we've been taking the opportunity to improve the architecture of the core and make things more extensible, so I'm optimistic about Sails + Waterline being easier to contribute to going forward.
I would just like to state that I emphatically agree with @yoshuawuyts's comments above. I know it's the holidays but I haven't really heard anything in the Issue Tracker or elsewhere from the core contributors in the past week as I've been getting interested in the project, and the build is broken on TravisCI, so that doesn't really instill much confidence in the project and make me want to contribute.
@nathanleclaire, I appreciate the criticism. Currently, I'm a bottleneck.
Personally, I've been pushing code to Sails, Waterline, and our other dependencies just about every day this and last week.
Re: confidence + contributions:
While I'd love for more folks to contribute new features to the Sails ecosystem, my main focus right now is on stability and getting the next release of Sails out. Contributions towards those goals are more than welcome! As soon as that's good to go, I'm going to work on our plugin system (hooks, generators, adapters) to make it easier for folks to extend core without requiring me to personally double-check everything to maintain reliability. Additionally, more reusable /versatile test fixtures are key here to making tests less opaque and making routes easier to unit test in general (I've started working on that, but have not finished yet)
@yoshuawuyts I'll nab that now, thanks for the reminder
I added a blurb on the new Trello board for feature requests (here's the one for coveralls https://trello.com/c/YnHAbOmE/1-coveralls-support-for-sails-core)
@yoshuawuyts @nathanleclaire thought both you guys might be interested in this. Going to get as much more as I can done this weekend, then going to have to drop off for a bit, but I think it's a decent start, and it feels good to get that stuff down on "paper".
A bit more good (if tentative) news is @particlebanana just got all the Waterline tests for v0.10 passing, so most of the struggle for us now is documentation and beta testing. I'll start a thread in the group when we're ready to start the "official" testing of 0.10+associations (we've got to get more docs together first)