New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.MD #1058

Closed
wants to merge 1 commit into
base: master
from

Conversation

4 participants
@yoshuawuyts
Copy link
Contributor

yoshuawuyts commented Nov 5, 2013

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.

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, because testing is a good thing.
  • A link to the changelog
  • A link to the roadmap (a Trello board with upcoming features would be awesome)
  • Add an overview of the architecture, much like Polymer did.

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

@yoshuawuyts

This comment has been minimized.

Copy link
Contributor Author

yoshuawuyts commented Nov 6, 2013

Updated the PR, would love to have some feedback.

@Thomasdezeeuw

This comment has been minimized.

Copy link

Thomasdezeeuw commented Nov 7, 2013

Under links: Development discussions points to Yeoman issues.

@yoshuawuyts

This comment has been minimized.

Copy link
Contributor Author

yoshuawuyts commented Nov 7, 2013

@Thomasdezeeuw Whoops, I'll fix that. Thanks for pointing it out.

@Thomasdezeeuw

This comment has been minimized.

Copy link

Thomasdezeeuw commented Nov 7, 2013

Looks good to me, nice work.

@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Dec 13, 2013

Love it man, especially the contributors section-- obviously this one needs to stay on master-- I'll come back to it after I catch up on everything else since I'd like to spend some time reading it more closely. Really appreciate your help.

some other stuff that might help out with the rest of the bullet points you identified:

roadmap

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.

contribution guidelines
changelog

https://github.com/balderdashy/sails-docs/blob/0.9/changelog.md

@yoshuawuyts

This comment has been minimized.

Copy link
Contributor Author

yoshuawuyts commented Dec 13, 2013

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

  • Rigorous issue smackdown; close everything that isn't relevant, combine duplicates into new issues.
  • Create a roadmap; add all feature suggestions to the roadmap and close corresponding issues.
  • Add code coverage via coveralls; it entices users to write more tests and fill up the bar.

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.

Good luck,

Yoshua

Update README.MD
Used the excellent [yeoman](https://github.com/yeoman/yeoman) docs to
build the refactored README. Also added a [Code
Climate](https://codeclimate.com/) badge.

README.MD should include only references and general information.
Exactitudes such as licenses, getting started and documentation should be
hosted externally. It now better reflects the essence of Sails and
properly seperates concerns.

update typos
@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Dec 15, 2013

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

@nathanleclaire

This comment has been minimized.

Copy link

nathanleclaire commented Dec 28, 2013

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.

@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Jan 1, 2014

@nathanleclaire, I appreciate the criticism. Currently, I'm a bottleneck.

Re: activity:
There are a lot of questions that find their way into issues here instead of StackOverflow, Google Groups, IRC, etc., which makes it harder to keep up with. Thankfully, @rachaelraygun has been going through and doing some issue maintenance to help get things organized

Personally, I've been pushing code to Sails, Waterline, and our other dependencies just about every day this and last week.
screen shot 2014-01-01 at 4 28 53 pm
I believe there's an RSS feed that Github provides if you want to be sure and keep up to date w/ the latest.

Re: confidence + contributions:
I believe strongly in the future of Node.js, and its ability to improve the development lifecycle, efficiency, and maintainability of all sorts of apps, from enterprise juggernauts to hobbyist projects. My team needed a framework, and Sails dramatically increases our efficiency. This is why it exists. However, we are completely bootstrapped, which means we don't have investment money raining from the sky, and unfortunately, we don't get paid anything for doing this.

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)

@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Jan 1, 2014

@yoshuawuyts Made separate issue for Coverall: #1254

@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Jan 1, 2014

@yoshuawuyts thanks again for the work on the README - I'm merging parts of it now

@mikermcneil mikermcneil closed this Jan 1, 2014

@yoshuawuyts

This comment has been minimized.

Copy link
Contributor Author

yoshuawuyts commented Jan 2, 2014

@mikermcneil Great to hear, the README is looking good! The only thing I'm missing is the h3 menu at the top, finding the docs / getting started isn't easy now.

@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Jan 3, 2014

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

@nathanleclaire

This comment has been minimized.

Copy link

nathanleclaire commented Jan 4, 2014

@mikermcneil Good on you man, and great to hear from you. Keep up the good work!!

@mikermcneil

This comment has been minimized.

Copy link
Member

mikermcneil commented Jan 5, 2014

@nathanleclaire thanks!

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

@yoshuawuyts

This comment has been minimized.

Copy link
Contributor Author

yoshuawuyts commented Jan 5, 2014

@mikermcneil Woah, nice work. Keep it up man!

@nathanleclaire

This comment has been minimized.

Copy link

nathanleclaire commented Jan 5, 2014

@mikermcneil Agree with @yoshuawuyts , awesome work man. I'll check out v0.10 soon and start looking into documenting associations.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment