Tips for writing a tech book

When I first started writing my book, Mastering Kafka Streams and ksqlDB, I had no idea what I was doing. However, as my book finally heads to the printer, I have decided to reflect on some of the things that helped me get to the finish line.

In this post, I will share some tips for writing a tech book that I learned along the way. I have kept this advice short and to the point, but if there’s anything you’d like me to expand on, please leave a comment at the end of the article. Without further ado, let’s take a look at my tips for writing a tech book.

Tips

Create a very detailed outline ahead of time

Writing a book is super stressful at times, but the outline will be your map if you feel lost or overwhelmed at any point. Also, getting eyes on your outline from industry experts ahead of time will validate your ideas and keep you from second guessing yourself as you get deep into the weeds.

How long will it take to create your outline? I assume it varies widely depending on the book. The outline for my 12 chapter, 400 page book took about a month to create and another two months to get approval from O’Reilly. In other words, it’s not a quick process, but you will be thankful that you have it once it’s time to start writing.

Start with an easy chapter, even if you end up writing out of order

This will give you an easy win and confidence to move forward to more difficult sections. Also, save some easier chapters for the end since you will be pretty spent by the time you’re nearing completion, and it’s a nice way to wrap up the project.

Before starting a chapter, write all of the code for that chapter

If your chapter includes a tutorial or code references, it’s best to write the code ahead of time. This will allow you to root your explanations in something tangible.

Create lots of visualizations

Images will not only make it easier to explain certain concepts to readers, but they will also help you, as the author, figure out the story you want to tell. This is why I spent a lot of time drawing diagrams whenever I started a new chapter. Not all of them made it into the book, but they helped get my head in the right place for explaining a concept.

There are lots of options for creating visualizations / figures for your book, but I personally like Miro. Also, sometimes a publishing company will want to redraw your images during the production phase. You should ask your editor about this so you don’t spend a ton of time polishing the minute details of your images if they are going to be redrawn later.

Be nice to yourself

Writing a book is difficult. For the first 6 months, I was working 7 days a week on my book (3–4 hours a night). After a while, I wanted to quit, but then I started blocking off Fridays to relax. It really helped me get through it.

Establish a schedule

I liked to write at night (8/9pm-12am). I know another writer who likes to write in the morning. Keeping a schedule helps establish the writing habit. Also, it’s important to take breaks. But predictable and scheduled breaks are much better, in my opinion, than random, unscheduled breaks. If unchecked, the latter can break your writing habit, and when you lose that rhythm, it can be difficult to reestablish.

It’s okay to miss deadlines

I felt really guilty about this at first, but sometimes it’s unavoidable. For example, your editor may not understand how long a specific chapter should take. They may give you 21 days per chapter, for example, without knowing that Chapter 10 requires a lot more time than Chapter 2. So don’t beat yourself up like I did if you miss a deadline, which goes along with the “be nice to yourself” advice.

Don’t create too many TODOs for yourself to address later

Some tasks can be pretty tedious. For example, labeling figures, adding titles for tables, getting footnotes right, etc. These small TODOs can take a lot of time to address if you allow them to pile up.

Release early and collect feedback

Release early versions of your chapters and set up a survey for collecting feedback (I used Typeform, but there are lots of other options, as well). O’Reilly has a dedicated Early Release Program for this, but the process may be more informal for other publishers. Either way, this feedback will put you in touch with your readers early on, understand what they like / dislike, and ultimately allow you to create a better book.

Create a website and build your audience

A nice landing page for your book is important for many reasons. First, it’s a great place for people to get updates about your book, especially if you include a signup form for a newsletter. Second, you can link to many useful resources from your page, including code repositories, feedback forms, social media pages, and more. It doesn’t have to be complicated, as you can see from the web page I created for my book, Mastering Kafka Streams and ksqlDB. I used Mailchimp to build my website and for sending email campaigns, and it works great (full disclosure: I work at Mailchimp, but it honestly works great and I would use them even if I didn’t work there).

Set Boundaries

A book will likely take hundreds or even thousands of hours to write. The sheer time investment means it will impact many areas of your life. But time is not something you will ever get back, so you shouldn’t let it consume a single minute of time that you hold sacred. For me, that was time with my daughter. I made a promise that I would never take time away from her, which is why I always worked on my book after she went to bed.

Did that make me extremely tired? Yes. But I don’t resent the time I spent on my book because I took it from the right place (my Netflix-and-chill time). If there are parts of your life that you hold sacred, defend them from your writing time so you don’t live in regret later.

Conquer Writer’s Block

Writer’s block can occur at any time and can be frustrating to deal with. After a few different bouts with this enemy of all writers, I figured out a technique that works for me. Whenever I couldn’t produce a paragraph, I started making lists. The bullet points on these lists became imperfect half-thoughts that I would use as breadcrumbs for describing a larger idea. They allowed me to focus on the smaller ideas that I wanted to communicate, and not the fabric of words that would ultimately weave them together.

In cases where a list didn’t help me flush out the section I was stuck on, it still allowed me to move onto the next section, where slight differences in subject matter could get the paragraphs flowing again. It’s difficult to skip sections entirely and still maintain a cohesive feel to your text. But if you flush out just enough of the problematic section in list form, you can easily revisit it later and maintain a higher level of cohesion between sections.

Celebrate Milestones

Everyone seems to focus on the biggest milestone of writing a book: publication. However, if you wait around for just this final milestone, you are ignoring many smaller victories that are also worth celebrating. The milestones that I think are worth celebrating include:

  • Getting the book contract signed
  • Completing the first chapter
  • Reaching the halfway point
  • Releasing draft versions of any chapter (e.g. via an Early Release program)
  • Completing the first draft
  • Reviewing copy edits and quality control (QC) edits
  • Publication and printing

Of course, how you celebrate is totally up to you. It can be a nice dinner, a night off from writing, etc. Whatever it is, take a moment to reflect on your accomplishments, since this will help you push forward to the next milestone.

Summary

Writing a tech book is difficult, but the above tips can make the process much easier and more enjoyable. I hope this helps you create something great. If you’d like to learn more about my book, check out my website. Thanks for reading!

Software engineer @ Mailchimp

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store