search

gruntjs / gruntjs.com

Grunt website
https://gruntjs.com
Other
155 stars 84 forks source link

Content Roadmap For Tutorials/Screencasts #69

Open kahlil opened 10 years ago

kahlil commented 10 years ago

Document all the things!

Suggestions welcome!

cowboy commented 10 years ago

@kahlil is going to start by creating one of these. Once we get the approach hammered out, we'll make it open to anyone to submit content!

contolini commented 10 years ago

Discussing common/best practices by dissecting a few real-world gruntfiles would be super helpful! Bonus points for a brief series of "Show Me Your Gruntfile" screencasts.

kahlil commented 10 years ago

Discussing common/best practices by dissecting a few real-world gruntfiles would be super helpful! Bonus points for a brief series of "Show Me Your Gruntfile" screencasts.

@contolini thanks for the input! After covering all the basics, best practices and dissecting Gruntfiles is definitely the plan.

codylindley commented 10 years ago

I'd like to second @contolini comment, and I believe this is actually need before more intros, how-to's, and tutorials.

A 5 to 10 minute screencasts simply describing what is occurring in production grunt.js file's (real world usage) would be ideal. Nothing in-depth, just educational so everyone can get an idea of the possibilities and flexibility of the plugin architecture, as well as discovering new uses of grunt and new plugins.

Maybe this could even be extended into a list of grunt files in github worth reading.

kahlil commented 10 years ago

@codylindley:

I'd like to second @contolini comment, and I believe this is actually need before more intros, how-to's, and tutorials.

A 5 to 10 minute screencasts simply describing what is occurring in production grunt.js file's (real world usage) would be ideal. Nothing in-depth, just educational so everyone can get an idea of the possibilities and flexibility of the plugin architecture, as well as discovering new uses of grunt and new plugins.

Maybe this could even be extended into a list of grunt files in github worth reading.

I love the idea. I disagree on the priority though. I think the low-level tutorials and screencasts should be done first in order to make it super easy for beginners and non-developers to start using Grunt.

I agree that the screencasts you describe would be extremely benefitial for developers to learn new tricks and discover cool new plugins. I also like the idea of a reading list of Gruntfiles.

If we can get a lot of contributions, maybe those two efforts can be run in parallel?

In order to do that, we need to talk about how we organize the different categories on gruntjs.com. Do we just add blog posts with categories or do we create landing pages for tutorials and discovery? I guess that should be part of the new architecture that will allow PRs for content contributions.

/cc: @cowboy, @vladikoff

cowboy commented 10 years ago

Great question, I'm going to cc @isaacdurazo as well regarding the IA of the site.

cowboy commented 10 years ago

Hey @kahlil, I think explaining how to split a large Gruntfile into much smaller, per-task files would be very helpful to Grunt users. Maybe a simplified version of this:

http://twitter.com/gruntjs/status/407586166792523776 https://github.com/cowboy/wesbos/commit/5a2980a7818957cbaeedcd7552af9ce54e05e3fb

What do you think? Can you add it to the list?

kahlil commented 10 years ago

Yes!!! Had that on my mental list already will add.

Sent from my iPhone

On 02.12.2013, at 20:19, Ben Alman notifications@github.com wrote:

Hey @kahlil, I think explaining how to split a large Gruntfile into much smaller, per-task files would be very helpful to Grunt users. Maybe a simplified version of this:

http://twitter.com/gruntjs/status/407586166792523776 cowboy/wesbos@5a2980a

What do you think? Can you add it to the list?

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

kahlil commented 10 years ago

@cowboy how do you feel about adding @sindresorhus load-grunt-tasks into this setup? https://github.com/sindresorhus/load-grunt-tasks

It is pretty neat to have just one line load all Grunt tasks.

kahlil commented 10 years ago

@cowboy added your suggestion to the list.

kahlil commented 10 years ago

Hey there @cowboy, @vladikoff, @shama, @tkellen, @sindresorhus

I just finished a new screencast:

Generating A Gruntfile with grunt-init: https://vimeo.com/91558869 (password: grunt03)

The first one was: Grunt Basics: package.json: https://vimeo.com/78207685 (password: dorkq)

My plan going forward is to make a few small screencasts on how to configure different tasks like concat, uglify and so on.

Then I would make a branch of the website and create a "Guides" section on it and add the screencasts on there as posts with respective articles for each screencast and then publish that on a heroku server for review.

I would love to know what you think of the direction I am taking and if you have any sort of feedback and criticism.

Cheers! :boar:

cowboy commented 10 years ago

@distilledhype I have a bunch of feedback about the package.json guide. Let me know what you think, especially about the stuff in bold.

General feedback

don't use dots in slugs, eg /scaffold-a-package.json should be /scaffold-a-package-json

let's call this entire screencast/article section "Grunt Guides" and refer to it by that name throughout, eg. "Welcome to Grunt Guides" (screencast branding too?)

Screencast-specific feedback:

I have a lot of nit-picky stuff here, but I feel that it's really important to get these guides right. If I were to condense my feedback down to a single main point, it's that I feel like we haven't done a good enough job identifying our audience. I think these guides need to explain Grunt to people who may only have a rudimentary grasp of what the command-line or Node or Npm or dependencies or version control or even tasks or automation or... JSON are. As such, we'll probably need to stay very focused and remove extraneous stuff, and be extremely careful about the terms and language we use.

For example, note how ideas are presented to people in this article, Grunt for People Who Think Things Like Grunt are Weird and Hard

Regardless of what I've written here, I feel like we need to take a step back and see how we'd explain what a package.json file is to a 6-year old who doesn't know about any of the concepts I listed above.

Here is my specific feedback.

"Node modules use package.json files to store package information and dependencies." -> "Npm uses the package.json file in your project to store information about the project and its dependencies." Then maybe add a "What's npm?" section with a description like "Npm is the command-line tool used to install Node Packaged Modules like grunt, grunt-cli and Grunt plugins. When you type npm install in a project directory that contains a package.json file, all the dependencies listed inside get installed, in one step." Maybe we need to explain what dependencies are.

"Grunt uses the package.json to consume meta information about the current project in order to use that information in Grunt tasks." - This isn't really true. Grunt doesn't care about what's in the package.json file, however you might optionally configure Grunt to read that file to get metadata about the project, like its name or version number.

"You don't need a package.json file in order to use Grunt but I would highly recommend it. Especially when you're working in teams." - I'm not sure about this line. If your project will be published to npm, it needs a package.json file. If not, you'll still want one because it allows you to specify what version of Grunt and Grunt plugins your project will be using.

"Another very useful function is the storing of development dependencies for the project. Having those dependencies stored in the package.json allow you to exclude the node_modules folder from version control because developers can install necessary node modules quickly by using the command npm install." - Think about the target audience for these guides. I think this sentence is going to be very scary for them. In it, you introduce the concept of "development dependencies" and "node_modules" and "version control" and "npm install" without explaining any of them! We need to really think about how we want to break concepts down into very easy-to-consume parts.

"There are a few ways to to do this.. The first option is when you use the scaffolding tool grunt-init, most of the templates will create a project-specific package.json file. This is actually also true for Yeoman. So when you use one of those scaffolding tools there is nothing else to do, you have your package.json." - Maybe up front say "There are three ways to create a package.json file for Npm to use in your project. You can use an external tool, like grunt-init or Yeoman which will scaffold out an entire project, including the package.json file. You can also copy and paste the sample package.json from the gruntjs.com 'Getting Started' guide and edit it by hand. In this guide, we're going to use the npm init command, since it comes installed with Node.js."

"As you can see npm gives you a nice explanation of what is going to happen. First it wants to know the package name. It has to be URL friendly in order to be valid. Next, npm wants to know the version number. Usually you would choose something like 0.0.1 or 0.1.0 to start with." -> maybe add "If your project will be published to npm, the name, version, and entry point are required. If not, you can use whatever you want there. Also note that if you just press enter, the default value in the parentheses gets used."

"Same goes for the entry point and the test command." - We should actually recommend that people specify "grunt test" for their test command and set up a task named "test" in their Gruntfile (to be covered in another article) so that when the "npm test" command is run, it actually runs the Grunt "test" task.

"gruntplugin" -> "Grunt plugin" - but really, this should be "If your project will be published to npm, you should enter relevant keywords..." - maybe this can get rolled into the previous comment.

"As you can see there is a bunch of stuff in there that we don't need. Throw out main, scripts and description and add the devDependencies property and we're done." -> This assumes they're not publishing to npm. What if they are? Also, I don't think you need to add a devDependencies property, because --save-dev will create it if it doesn't exist. Right?

kahlil commented 10 years ago

@cowboy thanks a lot for the elaborate feedback!

That's exactly what I need. I know there are a lot of rough edges, this will help me to refine it and make the guides consistent. I will go through all this asap and send a revised version.

kahlil commented 10 years ago

@cowboy regarding your feedback in bold: I agree with you 100%. I slightly missed the mark concerning the target audience I think. I will go through Chris Coyiers article again and adjust in accord with your feedback.

kahlil commented 10 years ago

@cowboy I finally read through all of your feedback and I agree with everything. I will completely rework the package.json screencast to reflect your feedback and to set a baseline in tone, look and language for all Grunt Guides with the target audience in mind.

Thanks again for all the feedback.

On Apr 15, 2014, at 3:29 PM, Ben Alman notifications@github.com wrote:

@distilledhype I have a bunch of feedback. Let me know what you think, especially about the stuff in bold.

General feedback

don't use dots in slugs, eg /scaffold-a-package.json should be /scaffold-a-package-json

let's call this entire screencast/article section "Grunt Guides" and refer to it by that name throughout, eg. "Welcome to Grunt Guides" (screencast branding too?)

Screencast-specific feedback:

I have a lot of nit-picky stuff here, but I feel that it's really important to get these guides right. If I were to condense my feedback down to a single main point, it's that I feel like we haven't done a good enough job identifying our audience. I think these guides need to explain Grunt to people who may only have a rudimentary grasp of what the command-line or Node or Npm or dependencies or version control or even tasks or automation or... JSON are. As such, we'll probably need to stay very focused and remove extraneous stuff, and be extremely careful about the terms and language we use.

For example, note how ideas are presented to people in this article, Grunt for People Who Think Things Like Grunt are Weird and Hard

Regardless of what I've written here, I feel like we need to take a step back and see how we'd explain what a package.json file is to a 6-year old who doesn't know about any of the concepts I listed above.

Here is my specific feedback.

"Node modules use package.json files to store package information and dependencies." -> "Npm uses the package.json file in your project to store information about the project and its dependencies." Then maybe add a "What's npm?" section with a description like "Npm is the command-line tool used to install Node Packaged Modules like grunt, grunt-cli and Grunt plugins. When you type npm install in a project directory that contains a package.json file, all the dependencies listed inside get installed, in one step." Maybe we need to explain what dependencies are.

"Grunt uses the package.json to consume meta information about the current project in order to use that information in Grunt tasks." - This isn't really true. Grunt doesn't care about what's in the package.json file, however you might optionally configure Grunt to read that file to get metadata about the project, like its name or version number.

"You don't need a package.json file in order to use Grunt but I would highly recommend it. Especially when you're working in teams." - I'm not sure about this line. If your project will be published to npm, it needs a package.json file. If not, you'll still want one because it allows you to specify what version of Grunt and Grunt plugins your project will be using.

"Another very useful function is the storing of development dependencies for the project. Having those dependencies stored in the package.json allow you to exclude the node_modules folder from version control because developers can install necessary node modules quickly by using the command npm install." - Think about the target audience for these guides. I think this sentence is going to be very scary for them. In it, you introduce the concept of "development dependencies" and "node_modules" and "version control" and "npm install" without explaining any of them! We need to really think about how we want to break concepts down into very easy-to-consume parts.

"There are a few ways to to do this.. The first option is when you use the scaffolding tool grunt-init, most of the templates will create a project-specific package.json file. This is actually also true for Yeoman. So when you use one of those scaffolding tools there is nothing else to do, you have your package.json." - Maybe up front say "There are three ways to create a package.json file for Npm to use in your project. You can use an external tool, like grunt-init or Yeoman which will scaffold out an entire project, including the package.json file. You can also copy and paste the sample package.json from the gruntjs.com 'Getting Started' guide and edit it by hand. In this guide, we're going to use the npm init command, since it comes installed with Node.js."

"As you can see npm gives you a nice explanation of what is going to happen. First it wants to know the package name. It has to be URL friendly in order to be valid. Next, npm wants to know the version number. Usually you would choose something like 0.0.1 or 0.1.0 to start with." -> maybe add "If your project will be published to npm, the name, version, and entry point are required. If not, you can use whatever you want there. Also note that if you just press enter, the default value in the parentheses gets used."

"Same goes for the entry point and the test command." - We should actually recommend that people specify "grunt test" for their test command and set up a task named "test" in their Gruntfile (to be covered in another article) so that when the "npm test" command is run, it actually runs the Grunt "test" task.

"gruntplugin" -> "Grunt plugin" - but really, this should be "If your project will be published to npm, you should enter relevant keywords..." - maybe this can get rolled into the previous comment.

"As you can see there is a bunch of stuff in there that we don't need. Throw out main, scripts and description and add the devDependencies property and we're done." -> This assumes they're not publishing to npm. What if they are? Also, I don't think you need to add a devDependencies property, because --save-dev will create it if it doesn't exist. Right?

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

cowboy commented 10 years ago

Thank you! Keep me posted on your progress.

kahlil commented 10 years ago

@cowboy

After having read through @chriscoyier's 24ways article about Grunt properly, I think my current work and concept might be missing the mark even more than I thought.

selfie-2

Instead of starting with the scaffolding tutorials for the package.json and the Gruntfile, I think the first Grunt Guide that goes online should be a complete "Getting Started" guide that shows the reader/viewer in very clear terms and the minimal amount of time

Everything that is not essential to know is left out, maybe mention links for more information. I think this could be done in a 5-10min focused screencast and it could be doing wonders in getting people off the ground that have absolutely now knowledge of any of this.

Many of the reactions to Chris' post were along the lines of "this should be the first tutorial in Grunt's documentation". Honestly, I basically agree I can see how it steers newcomers very quickly to the value Grunt creates for them and makes them want more.

I think we should follow up the getting started guide with more Task configuration examples, all the standard tasks like uglify, sass, imageoptim etc.

It's pretty much what Chris did just in our words and cut up into pieces and then extended from that.

Next we can go on to do Grunt Guides about scaffolding and the fancy stuff.

I will stop working on the package.json guide now and get started on the Getting Started guide next.

selfie-6

Thoughts?

(Silly gifs were done with a little help from Github selfies)

cowboy commented 10 years ago

@distilledhype awesome. I love it!

kahlil commented 10 years ago

@cowboy awesome. On it.

kahlil commented 10 years ago

@cowboy here is the draft for the script of the Getting Started screencast: https://github.com/distilledhype/grunt-guides/blob/master/scripts/01-getting-started.md

I'll go ahead and record that over the weekend. Feel free to drop some feedback if you have time!

kahlil commented 10 years ago

Status Report

I have written and re-written the new Getting Started guide and it has been edited by my wife who is a native speaker and an excellent writer. I believe the content is very solid now. I also recorded the audio for the screencast maybe 10 times over. It took my some time to find a tone I really like. I am trying to do the high standard of quality of the Grunt project justice while I work a full time job and side-projects, it's more difficult than I thought! But I think I am starting to see the light at the end of the tunnel. I will not give a delivery date for the finished thing but I am at stage where I feel I just have to put the parts together and I will do that in my next free time slots.

Just wanted to let you know that this issue is still very much alive and in progress...

cowboy commented 10 years ago

Thanks @distilledhype, I'm very excited to see what you've come up with. Let me know as soon as you've got something.

kahlil commented 10 years ago

Thanks @distilledhype, I'm very excited to see what you've come up with. Let me know as soon as you've got something.

I will surely do that.