Learning Yeoman

by Jonathan Spratley

If you are a web developer with some experience in JavaScript and want to enter the world of modern web applications, then this book is ideal for you. Learning how to leverage the three tools (Yo, Bower, and Grunt) in the Yeoman workflow will be perfect as your next step towards building scalable, dynamic, and modern web applications for just about any platform.

288 pages, ebook

First published January 1, 2014

Reviews

[dan · Rating 2 out of 5]

Packt Publishing sent me a digital copy of Learning Yeoman by Jonathan Spratley to review, so I did. They are compensating me with another free e-book.

substance
After a brief introduction to Yeoman, Chapter 1 starts you off with a complicated example of a web app with:
- an App object with 5 methods
- logging
- AJAX
- a 36-line Handlebars template
- app configuration embedded in the HTML

for a page that just ends up rendering static content. This is overkill for demonstrating the features of Yeoman and the webapp generator. The complexity is a distraction, which is a theme that continues throughout the rest of the book.

You might think this example is just setting up a base to be extended later, but this code is never revisited, nor is it using any of the frameworks that are the focus of rest of the book. Spratley just tells you to copy and paste the code in, and then gives a literal step-by-step description of what each piece of code does. He does not explain why it is structured the way it is or how you might use it as a basis for your own app. The code samples follow this same “copy, paste, restate” pattern through the entirety of the book.

The example unit test does not demonstrate best practices. It uses nulls, uses the more complex asynchronous test syntax unnecessarily, and includes 10 items of test data, but only actually uses one of them in the test. It doesn’t even actually test something significant that you may want to test in a real app; it just tests that the App object stores a given config object in a property. It seems like he just grabbed something at random for the sake of writing a test.

Spratley uses strange or just plain wrong terminology—often enough that it is a distraction to my reading. This gives me the impression that he is either pretending to be more knowledgeable than he is or is just careless in his choice of words. I will give just a few examples here:

- “The npm attribute is the package manager for Node.js”: npm is a tool, command, or executable, but not an ‘attribute’.
- “Just think of Yeoman as a helpful robot”: Yeoman is characterized as a yeoman (a servant), not a robot.
- “Connect LiveReload is the module that is a server that will auto reload when files are changed by the watch process”: the watch process does not change files; it watches them for changes.
- “Several testing tasks can be customized to do many useful things like showing test results in JUnit”: JUnit itself is a unit testing framework for Java. A Grunt task would just output results in a JUnit-style XML report.
- “The default Grunt task […] groups Angular modules into a separate minimized file”: this is still Chapter 1, which is only demonstrating the webapp generator, not the Angular one.

The book starts out using vanilla JavaScript, but in Chapter 3, it switches to CoffeeScript with no warning or explanation. The preface states that “this book is for newbies and intermediate web developers” and “you should have basic knowledge of HTML, CSS, and JavaScript”, but nowhere is CoffeeScript mentioned. I can only imagine that newbies who aren’t familiar with CoffeeScript would be completely blindsided.

Chapter 6 has you creating a custom generator with a Gruntfile with several tasks before Chapter 8 teaches you how Grunt tasks work.

Also troubling to me considering the book claims to be for newbies, is that it shows many generators without putting them in context or explaining when and why you would use each. Many of them are for advanced use cases; newbies should not be trying to create their own Angular directives and filters, generators, libraries, jQuery plugins, or Grunt plugins. I can imagine a novice hearing about Yeoman as the best way to develop web apps, buying this book, thinking that everything demonstrated here is a typical part of creating a web app, and being overwhelmed.

Another reason this book does not seem suited to beginners is that it presents the Angular, Backbone, and Ember frameworks, but only the Angular Chapter has a “Why Angular?” section that explains why you may want to choose it.


style

Overall, the book is no fun. It just goes through the motions, checking off each generator one by one with a different contrived example in each chapter. There is no overarching goal, story, or even just continuity between chapters. It would have been nice if it took you through building a larger project, with each generator solving a different piece of the same puzzle.

The book is very repetitive; not just in the content and structure, which could be argued to have some merit in reinforcement and consistency, but also in the style of writing itself. Take for example, the list of official generators from the beginning of Chapter 2:

- polymer: This is a generator used to create Polymer webapps and components
- chromeapp: This is a generator used to create a Google Chrome application
- jquery: This is a generator used to create a custom jQuery library
- gruntfile: This is a generator used to create a basic Gruntfile
- commonjs: This is a generator used to create a CommonJS module, including nodeunit unit tests
- nodejs: This is a generator used to create a Node.js module, including nodeunit unit tests

The phrase “this is a generator used to create a” composes the majority of the text in this list. It feels like the book itself was written with a generator! Even the authors can’t seem to tell some sections apart: in Chapter 7: Custom Libraries, the section on creating a CommonJS module has this conclusion on page 183:

In this section, we have learned about the CommonJS module format and how to create modules that can be used on the server side. We covered the basics of setting up testing.

Then, at the end of the next section on creating a Node.js module (page 189), there is another conclusion that seems it was also intended for the CommonJS section:

That was easy; now you should have an understanding on what a CommonJS module is and how to create one using the Yeoman CommonJS generator. We covered setting up a new CommonJS project, writing a unit test to verify the code works, and publishing the module to the npm repository. Now, you should be able to create CommonJS modules with ease and publish them to the npm repository.

On the same token, there is just a lot of extraneous verbiage, for example:

The serve task does a few things, which are as follows:
1. First, it removes [...]

which is just the same as saying:

The serve task:
1. removes...

Or this explanation of the directory structure of an Ember app:

- app: This is where the application source code is present:
 - images: This is where images for your application go
 - scripts: This is where the application logic scripts go:
 - controllers: This is for controllers
 - models: This is for models
 - routes: This is for routes
 - views: This is for views
 - app.coffee: This is the main Ember.js app file
 - router.coffee: This is the main application router
 - store.coffee: This is the application's data store adapter
 - styles: This is for stylesheets
 - templates: This is for Handlebar templates:
 - application.hbs: This is the main app template
 - index.hbs: This is the app index template
 - bower_components: This contains client-side Bower dependencies
 - index.html: This contains the application's entry point

The grammar is a bit wonky as well. It mixes active and passive voice all over the place, especially in “the preceding code does the following” lists, of which there are 41 (!). There are 11 occurrences of the word applications’, though I’m pretty sure they meant application’s in almost all of them. This mistake is not even consistent, either, as the latter spelling also appears 26 times.

Most of the links in the book are shortened with goo.gl, making each one a new mystery.


support

I had not read any books from Packt Publishing before, so I’ll comment on some aspects or their e-book support. Packt has its own online e-book reader. I tried it out and was disappointed.

- It has no keyboard shortcuts
- It does not remember settings across reloads
- It does not differentiate notes & tips by showing them in boxes like the other formats, so they blend into the main text and become distracting
- The table of contents is only two levels deep
- The “page” count displayed at the bottom is not pages, it’s 2nd-level sections. This is not enough to judge how far you are in a chapter, as some chapters only have three 2nd-level sections.

They offer an ePub file for download, too, but it also had problems. The code is wrapped too narrowly, and it has weird colors. The code is all blue and bold; the headings are a tacky orange, green, and red; and the body text is a grey color that does not give good contrast on either a light or dark background.

I ended up just reading the PDF version, which seems to be a direct representation of the printed book.


Learning Yeoman is complex, awkward, inaccurate, and unhelpful to beginners. I would not recommend this book. Just RTFM.