How I Wrote My First Technical Book

I just finished writing my first technical book, Production-Ready Microservices, and I've gotten a lot of questions about how I approached it, how I wrote it, and what the process was like from start to finish. The book is currently in the last stages of technical review and copyediting, so I thought I'd take advantage of this little break before I dive into writing my next two books and write something up about the whole process for anyone who is interested. 

When this year began, I didn't know I was going to write a book. Well, I knew I would write a book, but I didn't know that I'd write this book. I was working on a really cool project, standardizing the microservices at Uber, and I was having a lot of fun with it. I started talking to other engineers at various other companies that had adopted microservice architecture, and they wanted to know more about my standardization process. I spent a lot of time trying to figure out how to generalize microservice standardization so that these other engineers could use it, and by the time I'd done so, I was sending out pages and pages of written material. I thought this might make a great book, so I reached out to O'Reilly via their Work With Us page  and explained my idea. They replied with a formal proposal template, which I quickly filled in, and before I knew it, I had a book deal in my inbox. 

Because it was a technical book, I decided to approach it like an engineering problem. I treated the proposal like a good RFC: here's why the book is needed, here are the precise problems it will solve, here is the audience that will use it, here is why I am the best person to write it, and here is the precise, detailed architecture of the book. My goal was straightforward: architect the book, and then build it to spec. 

Writing the table of contents was probably the hardest part of the writing process, but it was (now that I look back) the most important part. I knew what I wanted to cover in the book (in a very general sense), but I didn't know exactly how and where each topic would fit. I first outlined the biggest topics: the basics of microservices, why microservice standardization is important, and then the eight production-readiness standards (stability, reliability, fault-tolerance, catastrophe-preparedness, scalability, performance, monitoring, and documentation). I decided to turn each of these into a chapter, and began making a bulleted list: 

  • Chapter 1: Microservices
  • Chapter 2: Standardization
  • Chapter 3: Stability
  • (and so on)

The next step was determining which subtopics I wanted to cover in each chapter. I began adding these to the bulleted lists, like this:

  • Chapter 1: Microservices
    • Basics of microservices
    • Why switch to microservices?
    • Splitting a monolith
    • Infrastructure needed for microservice architecture
    • Technical challenges of microservices
    • Organizational challenges of microservices

This still wasn't quite enough to precisely define the architecture of the book, so I added additional layers under each subtopic that looked a little like this: 

  • Chapter 1: Microservices
    • Infrastructure needed for microservice architecture
      • The microservice ecosystem
      • Layers of the microservice stack
      • Layer 1: Hardware
      • Layer 2: Communication
      • Layer 3: Application Platform
      • Layer 4: Microservices
      • How the layers work together and what they contain
      • How this differs from other architectural paradigms
      • (etc.)

I did this exercise for every chapter, and for every topic within each chapter. When I was finished, I had the full table of contents for the book. The whole thing was well-defined, and all I had to do next was write. 

Writing this book was so much fun, and it was also one of the most difficult things I've ever done. I work full-time, I have family, friends, and social obligations outside of work, I take courses (I was taking a grad course at Stanford for the first half of writing!) both at universities and on my own, and I have numerous interests and passions that I like to spend time on every day, so finding enough time to write during the week was difficult. I knew that I had to write every single day, though, or else it would take me many, many months to finish. 

I became very disciplined: I'd go to work, come home, and then write for 3-6 hours every weeknight. On the weekends, I'd write for 3-8 hours (until my brain turned to mush). I had a goal of writing at least 1,000 words every single day without any exceptions. It was extremely difficult at first, but eventually I got the hang of it and it became fun and easy. The detailed table of contents helped so much during this stage: I knew precisely what I needed to write about, so when I sat down to write each night I would pick the subtopic that sounded fun, and write everything I could about it. 

I wrote a total of two drafts of each chapter before I began sharing them out. The first draft was always messy, and not anything I'd ever want people to read. After I finished it, I'd take a break from it, work on another chapter, and then return to it with fresh eyes. I usually ended up re-writing the entire chapter on the second go, and the second drafts ended up much better than the first. Whenever I had the second draft of a chapter finished, I immediately sent it to several friends and coworkers who had (very generously!) offered to review it. The feedback I received from these initial reviewers was more helpful than any of them realized - every bit of feedback was valuable, and once I had all of the feedback, I went back to the chapter and re-wrote it for a third time. I repeated this process for every chapter until all of the chapters were completed. At this point, the book went out to my editor, and then to technical reviewers. 

It took me three straight months of writing every single day to finish the majority of the chapters. By the time three months had passed, and I only had a few subsections left to finish, exhaustion started to set in. I kept plowing forward, but I realized that I was learning something important about the way my mind works when I'm writing: I reach a certain point after several months where I need to set it down, put it away (regardless of whether it's finished or not), work on something else for a little while, and then return to it when I'm ready. I didn't know this at the time, and so I didn't do this, but I've learned my lesson and have scheduled these resting periods into the schedules for my next books. 

That was the most surprising lesson I learned while writing, but it wasn't the only one. As I mentioned earlier, I didn't realize when I began the book that the table of contents would be so crucial in the writing process. It took away any ambiguity, it gave me a mission and structure every day when I needed to just get the damn words on the page, and it prevented me from going overboard (by including too much) and from leaving important things out (by including too little). That's not to say that the table of contents was perfect from the beginning - I definitely changed it a bit as I wrote, moving several sections around and eventually deciding to merge several of the standards together in three of the chapters - but it never changed enough to be unrecognizable, and I truly wrote the exact book that I wanted to write when I sent the very first email to O'Reilly.

That's really all there was to it. I figured out what I wanted to write, architected the book, and then sat down every single day and wrote until it was finished. It really wasn't any more complicated than that. It just took some structure, a little discipline, a lot of time, and a lot of typing. I'm excited to see what readers think when it's released in the next few months. In the meantime, I'll be sitting at my laptop every night, working on my next book! 

(If you're curious about what the book looks like, you can download the second chapter for free from O'Reilly here: