Clear explanation of common grunt tasks.

[grayghostvisuals]

Referencing my convo with @sindresorhus over at grunt-contrib-imagemin Issue#47

To Summarize: We discussed the need for the Grunt docs to provide authors with a clearer explanation of common Grunt tasks.

[AurelioDeRosa]

This is a very old issue. Is there still an action needed for it or it can be closed?

[grayghostvisuals]

If you'd like but seems unresolved still.

[JKVeganAbroad]

I agree that it's old, but it still hasn't been resolved.

When I was a grunt newbie, the vague explanations in the Grunt docs (some of these I've resolved with pull requests) made the learning curve very high.

What we should do is write here a list of particular examples which need further attention in order to "complete" this issue.

[AurelioDeRosa]

Cool. I'll try to give it a go.

[AurelioDeRosa]

I had a thought about this issue and some questions came to mind. So, before submitting a useless PR, I'd like to ask those questions.

My understanding of of this issue is to add some examples of how to use common (=contrib?) Grunt tasks. However, the Grunt website doesn't have a dedicated page. Should such page be created? If so, what's the preferred name for it? Also, considering that many tasks already have a good set of examples, such as grunt-contrib-concat, grunt-contrib-jshint, grunt-contrib-connect, and grunt-contrib-qunit, is it worth to repeat them or even creating new examples in the Grunt website? Finally, aren't examples of tasks something that tasks authors should write in the project's repository?

If the intention of this issue is instead to list examples of specific tasks whose explanation needs to be improved, isn't this a matter of the specific repositories?

Thank you

[JKVeganAbroad]

A new dedicated page would be good, one that has a reasonably simple use-case scenario.

For example, copy files from 3rd party components folder (e.g. bower_components), concatenate with your source files, minify & uglify. Maybe preprocessing too.

It does duplicate many blog posts and tutorials on the internet, but it would complete the missing link in the Grunt Docs.

It's my view that you should look no further than the Grunt website to learn about why it's useful . . . What better way than to show a use-case scenario?

[AurelioDeRosa]

Hi @JKAussieSkater.

Thank you for providing this information. My last question is: isn't what we're trying to do here very similar to Sample Gruntfile?

As an alternative I can write an "Advanced Gruntfile" page where I show something slightly more complex and that uses different tasks. What do you think?

[AurelioDeRosa]

Friendly ping @JKAussieSkater

[JKVeganAbroad]

@AurelioDeRosa, yes! What we're trying to do here is very similar to the Sample Gruntfile.

Reading over the Sample Gruntfile now, there's a very high learning curve, it doesn't explain anything for new users, instead linking users to the respective plugin pages. What is uglify? Why are we concatenating? Why do we need to set up QUnit? What does JSHint do, and is it necessary? What does the file tree of the project look like before we Grunt, and what have we achieved afterwards that makes Grunt so wonderful?

I believe documentation for beginners should be self-contained—you shouldn't have to go to third party websites to learn the answers to these questions. As it stands now, the Sample Gruntfile is very confusing for beginners.

It seems to be explaining the syntax rather than explaining the purpose.

So where to from here? I can think of two options:

• Expand upon the existing Sample Gruntfile, making it a more comprehensive explanation
• Start a new page called "Why Grunt?" or similar