I wrote a book! Writing a book is something that stood on my bucket list of things I wanted to achieve, and I hadn’t considered actually doing it year. However, I got a great opportunity to work with Packt on the second edition of the Hands-On Kubernetes on Azure book. I am very glad with end-result, and even happier that Microsoft is distributing the ebook version for free. If you want to get your hands on a print version, you’ll have be a little more patient. The print book will be available sometime in April.
The reason for this blog post is to share my lessons learnt during the writing process. I learnt a ton during the writing process, both about the technology itself as well as about the process of writing a book. I wanted to share these lessons learnt, so that if you are considering writing a book, you can learn from a couple of my mistakes.
Clarifying the meaning of co-author
One thing I want to clarify is the word “co-author”. I only worked on the second edition of this book, my fellow co-authors had done the work of the original edition. In this second edition, we kept most of the structure of the first edition, with a couple of changes. However, all the explanation and all of the examples were mostly rewritten. We introduce a couple of additional concepts and examples in the second edition. The final chapter on Functions was fully rewritten, and now also includes an example of using KEDA.
I was very glad to be able to start of from a good basis, since the structure of the original book was pretty solid. The book builds from basic tasks such as deploying a sample application, to more complex scenarios like running Functions on top of AKS.
Getting the opportunity
I’ve got to thank Mike Martin for the introducing me to the publisher. The writing process started with Mike introducing me to Packt to do a technical review of the first edition of the book. The AKS product marketing team had approached Packt to license the book to distribute to Azure customers. Packt initiated a new technical review process to verify the content in the book was still up to date and relevant. I agreed to do a technical review of the book.
The previous version of the book was written and published a year ago, which is an eternity in the cloud and in the Kubernetes world. It was apparent to me after the review that the book needed major work to get updated. Most of the examples in the book didn’t work anymore (the upgrade from helm v2 to helm v3 was a major culprit), and some Azure implementations had changed as well.
Initially, I had just agreed to do a technical review of the book. I wasn’t planning at all to sign up and implement all the changes I had recommended. After the technical review I had a discussion with the publisher and they asked me if I would consider stepping in as a co-author and implement the changes if the original authors didn’t agree to write them. I had mixed feelings about stepping in as a co-author. Writing a book had been on my bucket list, but I didn’t know what I would be committing to. In those types of situations, I typically reach out to some people in my network to ask for advise. All of the people I talked to told me that this was a golden opportunity, and I finally agreed with Packt to co-author the book.
The writing process
If you’re considering writing a book, there’s a lot more work than simply writing the book. If I think about the writing process for this book, each chapter went through roughly the following stages:
- Initial draft
- Reviewed draft
- Second reviewed draft
- Proofed draft
- Prefinal draft
- Final draft
Each of those drafts requires you as the author to address the comments of the technical reviewer and the editor who works with you. It also requires you to keep re-reading each draft, so you might catch any inconsistencies and mistakes you might have made. In my case, I even caught mistakes I had made in the final draft.
In terms of work required, the initial draft, reviewed draft and second reviewed draft make up about 80% of the time investment required for each chapter. I personally had heavily underestimated the time required to redo each reviewed draft. The reason this required so much work is that often I needed to rework some examples based on input from the technical reviewers, as well as rewrite parts of the text blocks based on input from the editor and the technical reviewer. Rewriting often is more work than writing itself, because you need to ensure that the parts you rewrite fit in the overall narrative of the chapter.
Time investment required
Looking back at the e-mails I exchanged with Packt, we started actually working on the book on January 31st. I remember starting working on the book on a 5 hour flight from Detroit to Seattle, and realizing how little work I got done in those 5 hours. The final e-mail exchanged where actual content was discussed was March 16, about 6 weeks later.
During those 6 weeks, I spent about 3 hours every evening and about 10 hours every weekend on the book. A quick calculation makes this boil down to a total of about 150 hours, which seems like a realistic number to me.
An important note about the time investment is that I was religious about not mixing my day job with the writing. The writing of the book was something that fell outside of my day job, and was covered under Microsoft moonlighting policy. If you’re planning on also engaging on a writing a book, make sure you check your employer’s moonlighting policy and discuss this with your manager.
Working with the publisher
I was very glad to have the support of a publisher during the writing process. Packt had contacted technical reviewers, I worked with an editor that gave fantastic feedback, and they have a whole publishing apparatus that takes care of proofreading, copywriting and publishing. During the process, I could focus mainly on the content, and didn’t have to worry about any of additional tasks that are required for publishing a book.
If you are considering becoming a writer, I would highly encourage you start a first book by working with a publisher. I learned a lot about the writing process that I didn’t know by working with the publisher, and I believe it made the book more succesful.
Lessons learnt
The whole process gave me a tremendous learning opportunity. I learnt a whole lot about writing itself, the writing process and about the technology as well. Let me summarize the lessons learnt:
- You spend more time reviewing than writing. I mentioned this earlier, but this is top of the list for me. I had expected to spend a lot of time writing the book, but the end-result was that I needed to invest even more time than I had initially.
- Ask for the review of the initial chapters as quickly as possible. I was focused initially on writing most of the content “to get it over with”. However, during the writing process, I made the same ‘mistakes’ in every chapter. This meant that I had to re-do major parts of my work multiple times, in each chapter. If I had asked for the review of the initial chapters earlier on, it would have helped me catch those mistakes before I had actually written them.
- Flow between chapters and sections is super important. One of the mistakes I mentioned in the previous bullets was that I didn’t always include a perfect flow between different sections. The biggest piece of feedback I had gotten from my editor was that I ended examples and sections abruptly, and I should include a more natural flow between them. This means, when finishing an example or a section write a one or two sentence wrap-up and introduce the next step.
- Taking good screenshots is hard. A book will both be published in print as well as in digital version. Taking a good screenshot that works for both is harder than it seems. Too much information in a single screenshot won’t work for the print version since text will become too small. Too small a picture (resolution) won’t work for the digital version since this will not look well if zoomed into. Think carefully how you want to represent information in a screenshot.
- Think about how you are going to share examples. This might sound like an easy one, but I wanted to make sure to include this. Think about how you want to share examples. Do you want to store them on GitHub or just as a downloadable zip? How are you going to keep them up to date in case they break? Which code examples are you going to be using, and which filenames are you going to use to ensure the examples are consistent between the book version and the actual code.
Special thanks
There are a couple people who deserve special thanks, as they were instrumental in the writing process:
- Peter De Tender and Suleyman Akbas. They were the technical reviewers for this book, and gave extremely relevant comments. They tested all the examples in the book, and also reviewed all the content.
- Priyanka Sawant. Priyanka was a fantastic editor to work with. She made sure all my content was reviewed timely, and also gave very valuable comments and reviews to the work itself.
- My wife. While I was doing all the work, she had to pick up extra tasks in the household. We couldn’t nearly watch as much Netflix as we typically do. She had to deal with a lot during these past 6 weeks, and I’m very grateful for her understanding of the situation.
Summary
I enjoyed writing a book a lot, and given this experience I wouldn’t mind writing another one. If you are considering the same, I hope this post has given you more insight in the writing process and motivates you to get started. If you have any questions, feel free to reach out to me!