The Sin of Generalization

The more I progress in my journey as a software engineer, the more I realize how our profession suffers from the Sin of Generalization. The good news is that this sin can be fought with a rope and a mast. Let me explain.

This almost deadly sin manifests itself in two ways:

• A tool or a methodology that has been sucessful in one context gets generalized and becomes applied to other contexts, where it ill fits.
• A generic platform or framework is created to solve all sorts of needs, while ad hoc solutions would have been more straight to the point.

This may sound funny from me, as I am the lead of NxBRE, a .NET generalized rule engine! The reality is that NxBRE, like all rules engines and al generalized tools, has a sweet spot where its usage makes sense. Outside of this sweet spot, using a generalized tool is in fact counterproductive, because the indiosyncracies it is bringing (limitations, bugs, specific configuration...) outweight its benefits.

Of course, there is value in re-use and generic tools. The point of the matter is that it is always worth considering the relevance of a generic tool or methodology everytime you intend to use it. This sounds like an obvious statement but experience shows that generalized solutions are as attractive and noxious as sirens.

Hence the rope and the mast.

Mule in Action, the Making of

Now that dust has started to settle, I have some time to reflect on writing Mule in Action and share my experience with this process.

I will spare you the "it's a long and exhausting process that is a true trial for one's will", because you already know that such an endeavor requires a personal investment that is beyond whatever time-consuming hobby you could have (that is basically about sacrificing all evenings and Saturdays on the altar of authorship for a solid 6 months).

A technical book like Mule in Action gets its relevance from the richness and correctness of the examples it contains. Inspired by Brian Goetz's experience about writing Java Concurrency in Practice, John and I have decided to treat our examples like a full fledged project. For this we have created a Google code project and built all the samples with Maven. These examples are sometimes started by a command line script, but the true value resides in the unit and integration tests that cover them.

These tests are a life saver because the community edition of Mule 2, especially in its early days, was a moving target, with non-backward compatible API changes and deep behavioral alteration occurring between releases. Any time a new version of Mule is released, we upgrade to it and run a full build of the book examples. Anything that breaks signals a potential change in the book itself. But how do we know if the book needs to be changed and where?

We did not use a code extraction/insertion script, like Brian did, but we decided to enable a complete traceability by tagging our code fragments and keeping this tag along them in a hidden field in the body of the book. This way, whenever we modify the source code, we know if and where the book is affected.

This leads us to the format of the book itself. We opted for DocBook, which is "just" XML backed by a schema. What does this gives us? First, the possibility to grep for a specific code tag or sentence and replace using simple commands. Second, the possibility to diff two versions of the text (because, of course, we store all the chapters and related images in Subversion): this is extremely convenient in a multi-author environment like ours. And, finally, the possibility to use a simple but strict writing environment. Indeed, you do not need a word processor for writing a book: it is just a useless collection of bells and whistles. Any editor with schema validation and a basic spell checker is all you need.

That is for the tooling but what about the practice itself? I have quickly realized that, like a movie, a book is produced in an out-of-order manner. Trying to write a whole chapter in the reading order is futile and could lead to a very frustrating writer's block. Once I started to accept this idea, writing became way easier, with chapters appearing in the order inspiration was leading me to and backing code samples where being created. Even for a purely technical book, inspiration matters: it is a pretty stubborn animal that goes only the way it wants (am I talking about Mule?) and must not be forced otherwise.

Finally, I have found that music was an extremely powerful productivity booster. Maintaining a high productivity is essential for such a technical book, which is condemned to premature obsolescence if it is not written within a short period of time. Listening to lyric-less music was for me a way to boostrap my writing sessions, while oftentimes I would have preferred to call the day over and get some rest!

We struggled hard to stay away from writing a user guide, which is available on-line anyway, and opted to focus on practical examples touching most of the common and advanced usage of this ESB. Hopefully, the book will prove good enough for our readers to get both a deep and wide coverage of Mule.