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.
