Getting started should explain what Grunt actually does

[JamesHurburgh]

New to javascript web dev, I have no idea what Grunt is but I've heard the name and it sounds useful. So I go to 'Getting started' and I get 3 paragraphs on how it is installed and managed, then how to install the command line interface.

Then this: "Each time grunt is run, it looks for a locally installed Grunt using" What the heck is a Grunt? I thought that's why I was reading this page.

TLDR; The documentation is inaccessible to people who don't already know what Grunt is.

[AurelioDeRosa]

The Grunt homepage should answer all your questions. Taken from the homepage:

• Grunt, The JavaScript Task Runner
• Why use a task runner? In one word: automation. The less work you have to do when performing repetitive tasks [...] the easier your job becomes.

[ownsourcing]

We have to agree with @JamesHurburgh. Respectfully, the homepage does not answer questions that beginners have--not even remotely. There is a lot of information throughout the site, but it is pretty indigestible. Strengthening the first description of Grunt could go a long way to helping. Perhaps a rewrite of that paragraph along the following lines?

In one word: automation. Tell Grunt once about repetitive tasks you and your team need handled, and it does them forevermore, consistently, reliably, effortlessly. Give Grunt responsibility for minification, compilation, unit testing, linting, and a list of hundreds of other important steps that need to be run over and over. Once you list tasks in a Gruntfile, Grunt does that mundane work for you—following best practices tested and improved by a large community—with basically zero effort from then on.

The Getting Started sections are also a bit of a slog to understand. Those sections should be especially clear on what users must do themselves vs what Grunt handles out-of-the-box. Passive verb tenses are used both when describing features and when explaining required action. We recommend re-writing this section with imperative verb tenses. Give readers a set of instructions. Start each with the verb. End each with the object of the sentence.

@JamesHurburgh, does the above proposal seem in line with what you had in mind? Clearly the above can be improved further; ideally it gives a useable staring notion.

Grunt is truly among the great projects in open source. Kudos to the team and the community!

[JamesHurburgh]

Thanks for putting the effort into making this easier for new comers. That paragraph is descriptive and useful. Since you have a new issue to track the work I'll close this one.