Where should "Guides" content live?

[cowboy]

We've already talked about a Tutorials/Screencasts section of the site in #69. Now, we've got a user-submitted guide in gruntjs/grunt-docs#36.

I'd like to add this content to the site in a way that:

• Makes it easy for people to find what they're looking for.
• Encourages people to contribute new content.

Should we have both a "Guides" and a "Tutorials" section? Can these both live under one section? If we create a "Guides" section, should we move some of the existing content like Getting Started and Configuring Tasks into that section?

I'd really like to hear what people think!

/cc @isaacdurazo @vladikoff @distilledhype @shama @sindresorhus

[kahlil]

I think the IA should maybe be rethought here.

When you try to separate guides and tutorials it could get messy since there is no clear distinction for the user what the difference is between the two.

How about having one canonical guide that has a clear structure that contains essentially EVERYTHING. From simple basics to advanced usage.

This guide could also essentially consist of a phantasy project that Grunt is being set up for, this project could be on Github with git tags for the different states/steps of the project so that users can check out the different tags to see the different states of the project.

Each of the steps also could be illustrated by the screencasts that we are working on already and link back and forth.

People would have a clear entry point and a guide that takes them from novice to expert quickly and cleanly.

Defined entry points to the guide for different knowledge levels should be clearly marked.

That's my take on it. One guide to rule them all!

Thoughts?

Sent from my iPhone

On 15.01.2014, at 17:11, Ben Alman [email protected] wrote:

We've already talked about a Tutorials/Screencasts section of the site in #69. Now, we've got a user-submitted guide in gruntjs/grunt-docs#36.

I'd like to add this content to the site in a way that:

Makes it easy for people to find what they're looking for.
Encourages people to contribute new content.
Should we have both a "Guides" and a "Tutorials" section? Can these both live under one section? If we create a "Guides" section, should we move some of the existing content like Getting Started and Configuring Tasks into that section?

I'd really like to hear what people think!

/cc @isaacdurazo @vladikoff @distilledhype @shama @sindresorhus

—
Reply to this email directly or view it on GitHub.

[cowboy]

My concern with having one canonical guide is that it's going to be REALLY long. Individual articles are already very long, and are pushing the limits of what a user can consume in one sitting.

Plus, it would be great to encourage authors to submit stand-alone content, like what's in gruntjs/grunt-docs#36.

[kahlil]

Well the guide would have to be split up many many sections and articles and once the path for the guide is clear authors could submit parts or submissions could be worked in together with the author...

Sent from my iPhone

On 15.01.2014, at 19:00, Ben Alman [email protected] wrote:

My concern with having one canonical guide is that it's going to be REALLY long. Individual articles are already very long, and are pushing the limits of what a user can consume in one sitting.

Plus, it would be great to encourage authors to submit stand-alone content, like what's in gruntjs/grunt-docs#36.

—
Reply to this email directly or view it on GitHub.

[kahlil]

If not one canonical guide then I would argue for having one section either called "Guides" or "Tutorials" and maybe a section "Screencasts" since that's a very clear distinction.

That makes it very clear for the knowledge seekers I think.

Sent from my iPhone

On 15.01.2014, at 19:00, Ben Alman [email protected] wrote:

My concern with having one canonical guide is that it's going to be REALLY long. Individual articles are already very long, and are pushing the limits of what a user can consume in one sitting.

Plus, it would be great to encourage authors to submit stand-alone content, like what's in gruntjs/grunt-docs#36.

—
Reply to this email directly or view it on GitHub.

[thanpolas]

The difference between "Guides" and "Tutorials" is very subtle, the overlap is very big, i agree with @distilledhype that it'll confuse more than it'll help.

[kahlil]

Actually I think "Guides" might be the best choice because it is a little broader than Tutorials. what might be helpful would be to have sub categories. And also mark difficulty levels "Novice", "Intermediate" and "Expert" and define what is meant by those.

Just to briefly come back to the canonical guide: I think the EmberJS guide is a good example of this concept: http://emberjs.com/guides/