Refactoring docs

[am11]

Although we have this opened issue: #655, announcement in node-sass release notes https://github.com/sass/node-sass/releases/tag/v2.0.0, announcement in node-sass-binaries release notes: https://github.com/sass/node-sass-binaries/releases/tag/v2.0.0 and node-sass-binaries readme: https://github.com/sass/node-sass-binaries#node-sass-binaries (courtesy of @Turbo87); but still a lot of queries about node.js / io.js versions support have been made. It seems like the only place users like to look is node-sass' (swell) readme..

For that matter and the fact that readme is stuffed more than it probably should be, I propose we refactor the API and CLI usage sections from readme to GH Wiki, following the example set by LibSass: https://github.com/sass/libsass/wiki, while keeping the non-technical and status details (binary coverage matrix) etc. in readme. For the changelog, I like @jakobo's proposal to have a CHANGELOG.md, like we factored out the CONTRIBUTING.md from the README.md earlier.

Thoughts, ideas, suggestions? Please chip in!

@xzyfer, you're on! 😎

[Turbo87]

@am11 IMHO it is not a good idea to put the CLI/API documentation into the wiki, because then it would be versioned seperately from the source code. It would also no longer be possible to adjust the documentation from the same PR as the source code. I would rather propose to put that documentation into dedicated file in docs folder of the main repo.

The "Integrations" section from the main README.md is a different story though, and might as well be moved into the wiki instead as it is not closely coupled to the current version of the project.

[nschonni]

We use https://github.com/assemble/assemble/ but that is currently using Grunt. Bootstrap uses Jekyll since GitHub makes it easy to just have a gh-pages branch without having to compile.

[sindresorhus]

Using the wiki for docs is a bad idea: https://plus.google.com/+sindresorhus/posts/QSS2du26Mg4

[Turbo87]

@sindresorhus I agree completely

[am11]

👍

[quantizor]

The changelog is a must have - I'm trying to figure out the differences between v2 and v3 and it's extremely time consuming without one.

[xzyfer]

Current we use the release notes as a changelog. Tat allows us to be more
verbose than traditional changelogs. The information you need is there.
On 22 Sep 2015 08:11, "Evan Jacobs" [email protected] wrote:

The changelog is a must have - I'm trying to figure out the differences
between v2 and v3 and it's extremely time consuming without one.

—
Reply to this email directly or view it on GitHub
#730 (comment).

[quantizor]

@xzyfer What release notes? I don't see a file in the repo or link in the README to anything named that...

[saper]

@yaycmyk GitHub releases page: https://github.com/sass/node-sass/releases