Review comments: Chapter 6 - Backbone Boilerplate and Grunt - BBB

[dcmaf]

1. Chapter introduction states that Backbone Boilerplate includes a Windows/Mac/Linux build tool, but only includes command line instructions for obtaining it (instructions for Windows users are not included).
2. The build tools mentioned (pre-compilation, concatenation, minification) are not discussed in the chapter.
3. Grunt / Grunt-BBB installation section assumes reader is familiar with Node.js and NPM and has them installed. While chapter 5 does discuss installation of Node.js and using NPM, the reader may not have done so. It might make sense to break out a generic discussion of Node.js and NPM and their installation into a separate appendix that can be referenced by chapters that rely on them being installed.
4. In 'Creating a new project' it would be helpful to list the files (including paths) that were created before going into the explanations of what each one contains.
5. Since BBB generates a RequireJS template and much of the content of this chapter is discussion of what is in this template, I would recommend placing it after the Modular Development chapter. In that case, knowledge of RequireJS could be assumed and explanations could be reworked accordingly.
6. The app.js template references Backbone.LayoutManager and the concept of Backbone modules, neither of which are discussed in the text.
7. "Related Tools and Projects" could use descriptions of what Yeoman and Brunch are and how they differ from Backbone Boilerplate.

[addyosmani]

Thanks for your feedback.

1. It appears that the documentation for this has been updated since it was first released. Is your recommendation that we follow the readme and just mention Mac/Linux?
2. So you would like a description of the various build steps possible with the tool? If so that should be straight-forward.
3. I think moving the Node.js and NPM walkthrough to the appendix makes a great deal of sense.
4. I agree.
5. So, should we move the grunt-bbb section to after the RequireJS one and keep the Backbone Boilerplate section as is otherwise?
6. I think we should remove the reference in this case.
7. I agree. This should definitely be added.

[sindresorhus]

1. Grunt-bbb might be ported to Yeoman: Migrating to Grunt 0.4 backbone-boilerplate/grunt-bbb#89 (comment)

[dcmaf]

1. Yes - if it looks like it is not being supported on Windows then best to take out the mention.
2. Yes - would probably be a new section or two covering how to use the tools along with some examples.
3. I'm not clear on the distinction between the grunt-bbb section and the Backbone Boilerplate section. Don't you need to use Grunt-BBB to generate the boiler plate? At any rate, the generated boilerplate is dependent on RequireJS, so I would move the whole chapter to be after the Modular Development chapter. Maybe sequence them as: Exercise 2, Common Problems/Solutions, Modular Development, BBB/Grunt-BBB, Backbone Extensions...
4. Isn't the code in app.js generated by BBB? If not, then an example without them might be easiest; otherwise some discussion of them would be good.

[addyosmani]

I believe point 3 is the only one left to be addressed here. I'll tackle that once I've had an opportunity to look at any additional feedback on this chapter from other reviewers.

Thanks again @dcmaf!

[addyosmani]

Adding in the tech review from @wibblymat on this chapter (many of these points have already been addressed since) :)

The chapter is a very light introduction and few people will come out of reading the chapter ready to go off and use bbb without help. There are several unanswered questions. What does Backbone.Layout do? How does JST relate to other template systems? What is the purpose of bbb release? How do I actually use the new module I just generated? All of this stuff is on the web to be found but so is everything else in the chapter.

Perhaps rather than go into detail on how bbb works a better approach would be to introduce the idea and purpose of tooling - bbb, yeoman, grunt, r.js etc. - while directing the reader to learn more about them elsewhere.

There are some other problems with the current text:

1. There are instructions for downloading the Backbone Boilerplate repo from github but we never actually need it - you get it (as a sub-module of a sub-module) when you install grunt-bbb.

2. Remove the instruction npm install -g grunt. This is no longer appropriate as with this command you now get grunt 0.4, which should not be installed globally. bbb has a dependency on grunt 0.3.17 so once bbb is installed it will use it's own version of grunt to do things. I have removed grunt and grunt-cli from my machine and then installed bbb and all of the bbb commands work as expected.

3. I might also remove the instruction bbb init in the same set. If someone is just following along bbb init will create the project structure within the current working directory. Its annoying having to tidy up after making that mistake :) We give a fuller instruction in the very next section anyway.

4. The code samples for the project stub no longer match up with what you really get. They are in some cases quite different which could lead to confusion. The descriptions of what each file does are still basically correct, though.

5. Line 392:

   Now, you may be wondering where or how Views fit into this setup. Although Backbone Boilerplate doesn't include Views in its generated modules by default, we can easily add them ourselves as needed.

   Looks like bbb does now include views

6. Line 586:

   I'm happy to also recommend checking out Yeoman (one of my upcoming projects)

   It wont be "upcoming" by the time the book is out, it will be out :)

7. It might make sense to put this after the modular development chapter since you talk about AMD and requirejs config here.

[addyosmani]

I think I've addressed many of the points here. We've discussed the idea of having a section on Yeoman before and I just saw https://gist.github.com/crh/3852220 today. I've asked the author if they would be interested in writing up a tutorial using the latest version of Yeoman and the Todo app workflow we've adopted for the first exercise in the book.

[addyosmani]

@sindresorhus @passy I'm hoping to wrap up my work on this book this weekend and am currently trying to decide what to do about Yeoman.

As our Backbone generator is currently not 1.0 compatible (afaik), the only real option is to either (a) show a 0.9.x workflow or (b) just summarize Yeoman in a paragraph and try to cover something more detailed in the next edition of the book.

I'm tempted to opt for (b) for now, but just wanted to check what you thought. :)

[passy]

@addyosmani I'd opt for (b), too. The 0.9.x release isn't maintained and there appear to be some issues with newer versions of node and compass that won't get fixed, so I don't think it's a good idea to incentivize users to pick it up again.

[sindresorhus]

b

[addyosmani]

Thanks guys!