Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

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

Closed
dcmaf opened this Issue · 10 comments

4 participants

Marc Friedman Addy Osmani Sindre Sorhus Pascal Hartig
Marc Friedman
Collaborator
  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.

Addy Osmani
Owner

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.

Sindre Sorhus
  1. Grunt-bbb might be ported to Yeoman: backbone-boilerplate/grunt-bbb#89 (comment)
Marc Friedman
Collaborator
  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.

Addy Osmani addyosmani referenced this issue from a commit
Addy Osmani rearranging chapters as suggested in #322. Note that existing issues …
…will need to be updated to reflect this.
ef3b9a5
Addy Osmani
Owner

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!

Mat Scales wibblymat referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
Mat Scales wibblymat referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
Mat Scales wibblymat referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
Mat Scales wibblymat referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
Mat Scales wibblymat referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
Addy Osmani
Owner

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.

Addy Osmani
Owner

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.

Addy Osmani
Owner

@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. :)

Pascal Hartig

@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.

Addy Osmani
Owner

Thanks guys!

Addy Osmani addyosmani closed this issue from a commit
Addy Osmani Fixes #322 - adds more details about yeoman with differences between …
…it and bbb. Also added a mention of backbone devtools for kicks
a27605d
David Amend raDiesle referenced this issue from a commit in raDiesle/backbone-fundamentals
Addy Osmani Fixes #322 - adds more details about yeoman with differences between …
…it and bbb. Also added a mention of backbone devtools for kicks
fe349aa
David Amend raDiesle referenced this issue from a commit in raDiesle/backbone-fundamentals
Addy Osmani Fixes #322 - adds more details about yeoman with differences between …
…it and bbb. Also added a mention of backbone devtools for kicks

some corrections

refactored graphic, ,1/3 to more explanations for BasicView

gitignore

refactored graphic, ,2/3 to more explanations for BasicView

refactored graphic, 2a/3 to more explanations for BasicView

my changes all again about mobile chapter

some corrections

refactored graphic, ,1/3 to more explanations for BasicView

gitignore

refactored graphic, ,2/3 to more explanations for BasicView

refactored graphic, 2a/3 to more explanations for BasicView

small missing code syntax

update to grunt 0.4.0

fix update to grunt 0.4.0, enhance multi plattform support section

several layouting corrections, small enhancements, adaption of image sizing
95a40b0
David Amend raDiesle referenced this issue from a commit in raDiesle/backbone-fundamentals
David Amend raDiesle my changes all again about mobile chapter
some corrections

refactored graphic, ,1/3 to more explanations for BasicView

gitignore

refactored graphic, ,2/3 to more explanations for BasicView

refactored graphic, 2a/3 to more explanations for BasicView

my changes all again about mobile chapter

some corrections

refactored graphic, ,1/3 to more explanations for BasicView

gitignore

refactored graphic, ,2/3 to more explanations for BasicView

refactored graphic, 2a/3 to more explanations for BasicView

small missing code syntax

update to grunt 0.4.0

fix update to grunt 0.4.0, enhance multi plattform support section

several layouting corrections, small enhancements, adaption of image sizing

Fixes #322 - adds more details about yeoman with differences between it and bbb. Also added a mention of backbone devtools for kicks

some corrections

refactored graphic, ,1/3 to more explanations for BasicView

gitignore

refactored graphic, ,2/3 to more explanations for BasicView

refactored graphic, 2a/3 to more explanations for BasicView

my changes all again about mobile chapter

some corrections

refactored graphic, ,1/3 to more explanations for BasicView

gitignore

refactored graphic, ,2/3 to more explanations for BasicView

refactored graphic, 2a/3 to more explanations for BasicView

small missing code syntax

update to grunt 0.4.0

fix update to grunt 0.4.0, enhance multi plattform support section

several layouting corrections, small enhancements, adaption of image sizing

grammar and vocabulary corrections page 1 and 2 of 14

grammar and vocabulary corrections page 3-14 of 14
4141459
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.