Tim Juravich

Retrospectives on writing a 300-page software book

This post is a retrospective on a book I wrote in 2012. You can checkout the the listing on amazon.com, if you are curious.

In 2011, I was heavily involved with the PHP community and spent some time with Chris Anderson, one of the early committers for CouchDB and Co-Founder of Couchbase. Chris was kind enough to forward a publisher my way as they were looking for someone to write a book on PHP and CouchDB. On June 12, 2011, I signed the contract and got started. This post is my reflection many years after completing the book as a reminder for me next time I attempt to write another book.

About the book

The technologies were defined, but I had freedom to sculpt the details of the book myself. I settled on a book that enabled readers to:

  • Conceptualize a lightweight PHP framework from scratch.
  • Build and deploy a flexible Social Networking application using PHP and leveraging key features of CouchDB to do the heavy lifting.
  • Explore the features and functionality of CouchDB, by taking a deep look into Documents, Views, Replication, and much more.

My lessons learned

Overall, the experience was incredible challenging and also super rewarding. Below are the 5 keys lessons learned from that experience.

#1: Outline, outline, outline

I wasn’t adequately prepared to write a book of this size by myself. I created an outline and it flowed easily, but as I framed out the book I realized that going from this level of detail into just writing 25-page chapters was a fool hearty mistake.

#2: Be prepared to be humbled

I was deeply engaged with these technologies and have built several social networks myself, so I had misguided confidence that I can easily explain these concept and power through the book.

On the contrary, in some areas, I could feel myself over-explaining concepts that I didn’t need to. In other areas, I found myself needing to explain CAP theorem, ACID, and the rising trends of NoSQL databases. I had to triple-checking everything I wrote

#3. Creating software and writing about it, is crazily complex

Early in the book, it dawned on me that in each chapter I had to guide the reader through complex concepts, explain code line-by-line, and end up with a thoughtful solution at the end of the book. I quickly found myself creating the full application several times over, simplifying each time so that I could work backwards to guide the reader through it. I wasn’t prepared for the iterations, but this experience is one that shaped the way I explain and write software to this day.

#4. Be prepared for the revisions

My goodness. So many revisions and tracked changes.

The editor and team at Packt were wonderful, but as I processed through pages, I kept feeling as though my tone and depth of detail wavered based on how much coffee I had in my bloodstream at any given moment. Thankfully, my wonderful wife battled through all 300 pages many times over. Having a non-technical reader read through my insanity helped me piece together the important bits.

#5. Remember that you did it for the journey, not the destination

It took over 18 months from writing the first chapter until it was officially published. Throughout that time, the writing felt like it would never end.

I knew that writing a book about two incredibly niche technologies was never going to be career-changing. The money from the advance and royalties were nice, but writing the book was about proving to myself that I could and ultimately putting something that I created out into the world.

Final Thoughts

Technology changes fast

In this book, I used several technologies: “legacy”: PHP, CouchDB, jQuery, and Bootstrap. These technologies still exist, but are very different from what they were years ago and in some circles are considered “legacy” technologies. If this was to be re-written today, it would have a completely different technology stack.

On the other hand, as I read the book again, the architectural patterns and details used in the solution (e.g. tiered architecture, separation of concerns, and database design) are very much still valid today.

I’d do it again

It was a crazy journey and one that I’d do again.