The reality of writing a technical book

Published on 15 July 2016 , last updated on 1 August 2018

Two days ago I received my copies of Reactive Web Applications.

Stairways to Reactive

Stairways to Reactive

Needless to say, I had been waiting for this moment for some time. Even though the final PDF version had been out for a few weeks prior to this, nothing compares to holding in your hands an actual, physical, printed book and seeing the pages you’ve been working on in context with the possibility of turning them back and forth. Call me old-fashioned, but when it comes to reading a book with the purpose of learning new material I have the feeling that printed books have a better quality to it, with some form of tactile memory helping to remember the contents better.

In this post I’d like to try and review my experience of writing a technical book. I had written about the book before and talked about what it is like to write, so this will be the conclusion from writing this first book (yes, that’s right – there may be more, but not just yet).

Project duration and effort

Let’s start with some facts. I had my first call with Manning’s acquisition editor Mike Stephens on the 21st of May 2014 and received the printed version of the book on the 13th of July 2016. So that’s a little over two years in terms of total duration (I am not taking into account follow-up activities such as the book errata & possible updates to code examples).

In terms of writing duration, I started writing in July 2014 (the first commit to the book’s git repository is from the 21st of July and my calendar shows that I allocated time as of the 7th of July) and I submitted the revised version of the last chapter on the 18th of September 2016. After that there were of course more changes, but less of the constant, more time-consuming researching and writing.

I can’t say for sure how much time went into researching and writing, because I did not keep an exact track of the time. However I think that I can give a pretty good estimate given that I allocated time in my calendar for writing the book and usually managed to stick to it. From the 804 days (or 114 weeks and 6 days) of “writing duration” I estimate that I spent roughly 2 days / week with researching, writing, coding and reviewing the book, which is to say 230 days (or 1840 hours). Of course there were weeks in which I was writing less or not at all but there were also weeks (according to my calendar) in which I’ve spent 3 or 4 days in a row on the book. When the book went into production stage, I spent some more time on reviewing the copy-edit and proofreading for each chapter and the front matter. I think that in total this adds up another 5-7 days in total as it involved re-reading the entire book a few times. I don’t know how many authors do this last bit, it’s quite demanding in terms of endurance.

The importance of setting the right expectations

I now know that I could have done a few things differently (more on this in just a bit) but there is one thing I am very happy to have gotten right: the expectation that this is going to be a lot of work, and understanding that “a lot of work” may be a few days of work per week for a long time.

From the very beginning my goal for Reactive Web Applications was to write a book that pushes the reader to get their hands dirty and to apply the theory in order to get a chance to “feel” the concepts being thought in practice. Of course this approach is more demanding on the part of the reader but from the feedback that I’ve gotten so far it also pays off in terms of learning the concepts and being able to apply them in practice in a real-world project (come to think of it, this is probably a result of my education at the National Institute for Applied Sciences – and of the very real focus on the “Applied” aspect throughout the curriculum). On the other hand, this also meant building, evolving and maintaining quite a few example applications during the course of writing the book and keeping the source code in sync with the manuscript . This can’t be that easily automated because the manuscript version evolves over the course of a chapter – which is to say, I did it by hand. Many thanks to my technical reviewer Vladimir Kuptsov for spotting all the glitches during review!

Writing continuity

When we met at the Scala.io conference in Paris in late 2014, Nilanjan Raychaudhuri (author of Scala in Action) told me that there are 3 ways to write a book:

Given that I work as an independent consultant I took the approach of viewing the book as a different client and allocating a few days a week to it. The trouble with this approach though is that you loose the continuity of writing – there’s two days of book and then 5 days without writing, which turns out not to be very efficient because it takes time to get back into “writing mode” after 5 days of breaks. In the end, what worked best for me was to write a few hours on the book every morning, every day of the week (and on the week-ends from time to time). When I say writing, by the way, this includes researching, coding, updating the Play version throughout the book and other activities related to producing a technical book.

The technology never sleeps

While I was writing Reactive Web Applications the Play Framework evolved, Scala evolved, Akka evolved and Akka Streams… let’s just say that Akka streams aggressively re-invented itself at every release candidate and at the first release of version 1.

The reality of writing a technical book is that the technology will change while you are writing it and there is not really much that you can do about this. I tried to find the right balance between picking interesting examples and “stable” ones. At the core of the book are functional programming principles applied to asynchronous programming, which are concepts that are going to outlive all technologies described in the book. I also tried as much as possible to ensure that the example applications work and that no dependencies are missing – I can’t even start to imagine how it must be to write a book in the Javascript space where dependencies break beyond your control due to the strange take of “range versions” that are allowed in the Javascript / Node / NPM space. This meant sometimes using the older version of a library rather than the newest shiny snapshot version which could potentially disappear after the book was released (e.g. chapter 7 uses akka 2.3 because at the time of the writing, one library used in the chapter only supported this version).

If possible, I would have liked to have the book come out with examples using Play 2.5 instead of Play 2.4, but the timing was just not right – the planned release date of Play 2.5 was postponed, then the book took some time to be scheduled for production and so in the end the examples are still using Play 2.4. That being said, the changes between the versions are not too large and the examples in the book already promote the use of dependency injection over global state, which is one of the largest changes between those versions of the framework.

You cannot write a technical book alone

As I’ve written in the acknowledgements section of the book, there wouldn’t be a Reactive Web Applications book today if it weren’t for the support, insights, inspiration, encouragement, and feedback from a whole lot of people. To everyone involved: thank you!

Unless you are the creator of the technology you cover, I don’t think that it is possible to write quality book on a topic without reaching out to many more people. And I’m not even talking about the help provided by the publisher when it comes to things like editing, reviewing, copy-editing, proofreading etc. but about the content itself. Like software, a technical book covers so many aspects that you have to talk to as much people as you can to get the big picture as well as all those small details that make the difference. And like sofware, there are bugs: things you do not see as an author, expressions that are unclear, incomplete trains of thought, etc.

In conclusion

During the course of this blog post, you have learned:

I don’t know yet if I’ll write another book. But I’m not entirely put off by the idea either, so we’ll see. To all readers: submit any errors you find here. And of course I’d love to hear your feedback!

Lastly if you want to keep up-to-date with news regarding the book, the reactive ecosystem and what I am doing, you can subscribe to the newsletter. Cheers!

The End

The End


Liked this post? Subscribe to the mailing list to get regular updates on similar topics.

Leave a Reply