Search this site:

[review] Packt's «Instant Haml»

Packt Publishing sent me Krzysztof Nikiński’s «Instant Haml» to do a short blog review… Thing is, and those who read me know, I cannot write short reviews ;-) So lets see how this goes.

Packt's Instant series

First, as for the format this book follows and the series it fits in: They are very short books. I was the tech reviewer for their «Instant Debian – Build a Web Server», and when I opened it for the first time, I thought I had received only the first chapter. This series’ motto is Short | Fast | Focused — so, yes, the books are ~50 pages long, with ample margins and many big screenshots. I told the editors I was quite unsure about the value this kind of publications add, as they are very similar to online tutorials, but given they have so many books in this series (printed and electronic), there must be a market for them. They surely know their business better than me!

There is one other detail regarding the publisher I’ll stick in this section, although it is not specific to their Instant series: I do most of my reading in my Kindle. Packt seems to have chosen to specify a very small font for their texts. Besides the two books mentioned, I also have their Object Oriented JavaScript book. For all of the other books I read, I use the smallest font setting. Packt books in </tt>mobi</tt> format (what they present as Amazon format in their web site) are basically illegible without bumping up the font size through the roof. As I understand it, publishers should use industry-wide default sizes, and let the reader adjust their reading experience. Yes, books of technical nature (such as Packt’s) often benefit from having more displayed information than what an ebook reader normally shows… But that’s for me to decide! And no, this is not a Kindle-specific glitch: I also get a similar experience when opening it from Calibre.

And as for the book...

I am a long-time Haml convert/fan; I packaged its Ruby implementation for Debian (and should update it soon :-/ as new versions have appeared), the corresponding Emacs Lisp mode, and I use it for basically all of my static HTML sites and Ruby-based Web systems.

Haml is a great templating language, meant to make dynamic HTML generation leaner and easier. It is a clean and elegant technology, and can clearly sell itself. And the project webpage has very good documentation, ranging from a short tutorial and a full API documentation for people to contribute to the project.

The first part of this book, of course, covers the “why is Haml so great?” part, presenting the basic equivalences with HTML. In my opinion, the book could be structured a bit differently and would generate a stronger following. Why? Because, even given that Haml is greatly benefited from its Ruby integration and has many hooks to be tightly integrated in a Rails workflow, it can also be used by people who don’t want to do Ruby.

I have some static websites that are just a bunch of Haml files, compiled by a very simple Makefile and calling the haml command from the shell. I think there would be some value in presenting this invocation before learning how to call it from the Gems environment (i.e. bundle install).

Using Haml as a standalone tool is only presented almost as an appendix (“Using HAML outside of Rails” section). Even more so if the author presents four different static-site solutions (probably more non-programmer-friendly than my trusty Makefile).

Oh, and this little section uses the (old? obsolete?) uppercase HAML notation for the project’s name instead of the now-standard Haml.

Dirty screenshots

About the screenshots presented in this first section (and I refer mainly to the scaffolding examples), they are meant to show how easy things are, but have an important stylistic mistake: Terminals with transparency might look cool (I hate using them, but then again I’m a very boring person when it comes to my computer habits ;-) ), but transparencies have no place in a book (be it printed or e-book), as the images appear very uncrisp. In the Kindle, they just seemed dirty — Now that I’m browsing the PDF from my desktop, I see that the screenshot in “Step 1” has a photo of Earth from space behind the terminal, and even worse, in “Step 2” it is shown over a Web page detailing the installation! These elements are just distracting, and the text would be much cleaerer if it were presented typeset just as a regular code fragment. Opening many of those screenshots in the Kindle was plain useless.

Editor integration

It is perfectly clear from this text that the author strongly prefers Sublime Text, sometimes uses TextMate, and has just heard reports that Haml has some support in Vim, Rubymine, Emacs and Coda. Of course, devoting a full page (as it is for the first case) for each editor would be out of proportion for this size of book… I just felt the imbalance too big, specially given that most editors will sport approximately the same feature set.

Text redundancy

If the Instant series is about making short books, I would expect them to be loaded with easy to follow content (as they are), but free of repetition. I felt, however, a large chunk of step 1 of the “Quick start” chapter to be repeated with the the first section of the “Top 6 features” chapter. Yes, the second one adds some depth, but very little. Still, in the later parts of this “Top 6 features” chapter, a more thorough explanation could be used for the Filters, Multiline attributes/code/strings and helpers and extensions sections. It seems the author was on a hurry trying to get it finished, as it is barely explained — Explaining a bit more deeply would surely benefit readers.

Wrapping up

Reading my review, I’m mostly talking about negative issues. IMO, the book is not excellent, but it is clearly not bad. Specially given it fits very well the format for which it was designed. There are many items that could be fixed, and I hope some of them can be fixed (i.e. the screenshots) before the book goes to print — If I understand Packt’s page correctly, it is currently only available as ebook, contrary to most of the Instant series’ titles.