Update: make sure to read part II of this post as well to learn how I improved this process for my next book

I started the whole project wanting to follow up on my earlier free PDF document on how to use FitNesse in a .NET environment. Instead of a quick and dirty guide, I wanted to create something that would give readers a more complete overview, present both the tool and important underlying practices and offer some ideas how to effectively use it in real world projects. I thought about giving away this as a free PDF as well, but then decided that I want to create a proper book which involved paying someone else at least to copy-edit it. So I decided to try out a commercial print to cover the production costs.

Print-on-demand is a new generation of printing services, where books are not issued in batches of a few thousand, but printed a copy at a time. Several on-line stores offer this service now, and I chose to use Lulu.Com because it seemed to be the most popular at the time. In addition to printing, they offer to sell the book on their web site and push it through their distribution channels to major on-line stores as well. The concept seemed interesting, especially since I worked as a technical editor on more than 20 books for a traditional publisher between ’99 and ’05. Back then, it was not worth it to print anything less than 1000 copies at a time, and the idea of having a single copy of the book printed and bound for a few pounds was so crazy that I had to try it out.

Lesson #1: It does not take a lot of money to publish a book, but it takes a lot of effort. In total, I have spent a bit more than £1000 to get the book published, most of which was for copy-editing. I could have saved a few hundred pounds I was not looking for a copy editor with a very specific skill set: reading and editing XML files directly. Because the copy-editor changed the source XML files directly, I did not have to manually enter changes from a paper copy or from an exported Word document, so this saved a lot of time for me.

On the other hand, getting a book from concept to cash takes a huge amount of effort. In total, I spent about nine months working a few hours per day on the book. I did not fill in any timesheets for myself, so I do not know the exact figure, but I estimate that I invested between 500 and 700 hours into this project. Half of that was writing the book, the other half was preparing the book for print and solving publishing problems.

Lesson #2: The book is a great marketing tool. I never expected that my book will be the next Harry Potter, so the commercial side of it was not really that important to me as long as I covered the costs. So far, the book sales have covered the production costs and I’ve earned a bit of money as well, if I don’t count my own time spent on the effort. However, In terms of contacts and contracts that I got because of the book, the experiment has been quite fruitful. So, the money in/money out balance of the whole project is hard to calculate. I like to believe that it was worth it .

An additional bonus is the fact that I learned quite a lot while researching for the book. I started the project convinced that I knew all there is to know about TDD and FitNesse, but I wanted to present a balanced view on best practices so I made myself read up a lot of blog posts and articles on agile acceptance testing and TDD. That allowed me to gain a much deeper understanding of the matter and fill in a lot of gaps that I did not even suspect I had. It was truly an eye-opening experience.

Lesson #3: DocBook rocks! Since I was financing the whole thing, I wanted to keep the production costs as low as possible but get a solid result. I looked for ways to automate and optimise everything I could. DocBook is the programmer’s publishing system, generating the book PDF from a simple XML markup system. It allowed me to write chapters as plain text files (XML), which makes versioning and collaboration incredibly easy. The three biggest problems I can remember from my involvement with a traditional book publisher are tracking changes, consistency of cross-references and making sure that the source code for examples included in the book can actually run. DocBook solves all problems fantastically easy. My copy-editor changed XML files directly and I could use diff to quickly identify the changes. I used subversion to version the files. DocBook supports cross-references that are resolved when the book is compiled into PDF, so it automatically inserts the title and real page number of the target section for me. Code files, images and things like that can be included externally, so the book was built using C# files that were compiled and unit tested as well. DRY to the max!

DocBook is not without its flaws — for example, it would be great if the standard supported embedding parts of code files (so that I could insert a snippet and not the whole source file). Some XML tags are too complex, like the one for linking to an external image. Since DocBook works on plain text files, all those issues can easily be resolved by external shell scripts.

Lesson #4: I need commercial tools for this. I tried to do everything with opensource tools, using Docbook on Linux, with Xalan to convert Docbook-XSL to XSL:FO and and FOP to transform that to PDF. The tools did the job, but with too much pain. Docbook is a great idea, but FOP (0.94) broke so often and with such unusable error messages that I wasted hours on fixing trivial issues. NullPointerExceptions get thrown when stuff cannot fit on the same page, but nothing tells you what stuff or which page. This is especially hard to fix when individual chapters can compile correctly, but the whole book fails (eg because resolved links add a line to the page, that moves the image to the next page and then we get a NullPointerException).There a few commercial XSL-FO tools, but my budget for this book did not allow me to buy one. Next time, I’ll definitely get a commercial tool to do the job.

Lesson #5: Don’t trust PDF files. Unfortunately, “It works on my machine” syndrome applies publishing as well. When my book was ready for the first printing, I ordered a test copy, spent twenty days waiting for it and then tried to chase it through the printer’s customer service. It turned out that the PDF was unprintable on their machines and they could not give me any explanation why. I had already printed an earlier version of the book through the same printer and I had changed the fonts meanwhile, so changing the fonts again was my first idea how to fix things. Since I did not know which font caused the problem, I replaced all the fonts and re-submitted the PDF. This time, the book came out in a week. I thought that PDF is platform-independent and that if I can view and print it, it should be the same with the printer’s machines. Unfortunately, that was a false promise. The consequence of all this: about two months of delay and my code font was not nearly as good as I wanted it to be. Trying out another font would delay the print even longer, so I decided to go with this one.

Lesson #6: Leave a big margin for mistakes. This is probably what hurt me the most. On-demand publishing process is not necessarily repeatable. They use local printers to satisfy requests around the globe, and the test print which I approved in UK is not necessarily the same as the one that US customers will get. When I finally got something that printed OK with all the font changes, the front and back covers were not ideal — it would have been better with a bit more space between the letters and the cover edges, but I was nervous to get the book done and I decided to go with the covers as they were. They seemed OK, so I thought that the covers don’t have to be perfect and that I’d rather get the book finally published. A few weeks later, I got complaints from some US customers that some letters were cut out on their covers. The text and images on the US print covers were, apparently, displaced half an inch compared to the UK print covers. I changed the covers and re-submitted the book, which gave me a chance to fix some other minor issues with the text but delayed the distribution for another month.

Lesson #7: Everything takes much longer than you expect. I suppose that I got used to the speed of change in software. Even with full pre-press on my machine, any slightest change to the book takes at least a week, because the printer has to print and ship it and it has to arrive in the post. In case of problems, it can take even longer to find that out. Customer support at Lulu is very accessible, meaning that they are available on instant messaging 24/7, but I did not find them particularly helpful. A few times when I had real problems, like that font issue, it took them at least two days to respond and they did not offer a resolution to the problem. If you want Lulu to dispatch your book to Amazon and Barns and Noble, it takes them about a month to review it. If they have any objections, even though it takes you ten minutes to fix it, it still takes them another month to re-review the book and approve it for distribution. From that point, it takes a few months for the book to actually appear on online stores.

Although digital pre-press, working with PDFs and automated typesetting and layout speeds up the work and makes it much more agile then with a traditional process I have seen before, the time to see the result is still not negligible. Granted, a lot of errors and problems can be caught with the PDF, but I would not believe the PDF for the final confirmation that everything is OK. Just for reference: I had the text with initial layout finished in early November last year, but the book was officially announced and started selling on Lulu.com in mid-January. It appeared on Amazon in late April this year.

Update: make sure to read part II of this post as well to learn how I improved this process for my next book

Image credits: Joana Croft

The book is a summary of my experiences with FitNesse in a .NET environment on several large projects. It covers the following topics:

- Applying test-driven development principles and practices to guide projects and improve the quality of code
- Writing FIT/FitNesse tests for .NET code effectively
- Getting customers involved in testing
- Building a shared understanding between business people and developers using acceptance tests
- Setting up and managing FitNesse in a team environment
- Using FitNesse and Selenium for Web interface testing
- Testing legacy code and databases
- Extending FIT to meet particular project needs
- How FIT and FitNesse work under the hood

The book is primarily aimed at .NET developers interested in starting with TDD and those who already practise unit testing and want to move beyond that into development driven by acceptance testing. It will also be useful to Java developers who are experienced with FitNesse, but wish to use it in a .NET environment. Java developers can also benefit from the third part of this book, which presents best practices for using FitNesse in a team environment and integrating FitNesse into the wider software development ecosystem, including web and database tests.

For more information, see http://gojko.net/fitnesse/book