I’ve been asked for advice about writing a book several times since The Missing README came out in August. This post is my attempt at an answer. If you’ve ever thought about writing a book (or are just curious), read on.

Know Why You’re Writing

Writing a book is a long journey. You need to be clear about your motivation. I tell people, “Don’t write a book because you can. Write a book because you can’t not.” Your motivation should be intrinsic. If you don’t have a very strong and enduring drive, you will fail.

A desire to learn, to help, to teach, to clarify or share an idea, to address a gap in the market; these are good motivations. Money and prestige are not good motivations. You’re not going to get rich writing a technical book.

Dmitry Ryaboy (my co-author) and I have found joy in the feedback and reviews we receive. It’s nice to know we’ve helped people. This, alone, can go a long way in justifying why you write.

Assess the Market

An intrinsic and enduring motivation to write isn’t enough. You need to answer two more questions: why does your book need to be written, and why does it need to be written by you? These are the two questions that publishers want answered. The following templates will help you find your answers:

• O’Reilly Media’s Book Proposal Template
• No Starch’s Book Proposal Template

Fill one of these templates out, even if you’re not planning to use O’Reilly or No Starch as your publisher.

It’s fine if there are books similar to yours; in fact, that’s a good signal that there’s a market. Your book does, however, need to differentiate itself in some way. You can differentiate by length, audience, author, style of prose, depth or focus of coverage, and so on. Maybe other books are academic and yours is applied. Perhaps other books are written by laymen and you’ve got 20 years of experience. There are many ways to cut it, but you need to be clear about how your book will stand out.

You might not be an expert on everything you want to write about; this is fine. Dmitriy and I found ourselves doing research on some topics while we wrote, even though we were covering introductory material! Knowing something and being able to explain it are two very different levels of knowledge. The book was better for it.

Everything else you do will derive from what differentiates your book, so figure this out early. What sections you write about, what your table of contents looks like, the style of prose, how you market the book, the book’s cover, and so on.

Build an Audience

Start a blog to test your determination and to assess the market. Put out a post every week or two for a sustained period–at least 3 months. If you can keep up this pace, it’s a sign you can sustain the pace needed to write a book.

The traffic to your blog will also signal whether there’s a market for your writing. If you’re putting out content and no one is reading it, your book is going to be harder to sell. It’s possible that no one is reading your posts because you don’t have distribution–Twitter followers, LinkedIn followers, Hacker News upvotes, Reddit posts, and so on. This is still a valuable signal; you need to build these distribution channels while you write.

Find a Publisher

Find a publisher while blogging and writing your first few chapters. You can self-publish or go with a traditional publisher like O’Reilly or No Starch. Consider both paths before making a decision.

I have zero experience with self-publication, so my best advice is to talk to the community at techwriters.dev. The TechWriters Discord was founded by the inimitable Will Larson (a.k.a. Lethain, author of Staff Engineer and An Elegant Puzzle). The community is a collection of both independent writers and bloggers, as well as traditionally published authors. You’ll find a wealth of knowledge in this community.

NOTE: I post stats and other findings on #book-missingreadme, if you find the content in this post interesting.

Talk to more than one traditional publisher to get a feel for how they work. Pay close attention to the editing experience. A good editor will make your book much better. Our editor, Athabasca, improved our book in ways Dmitriy and I could never have. (If you’re self-publishing, definitely hire an editor.) Send each publisher a sample chapter and ask them to edit it. Evaluate both the editing process and the feedback you get.

Ask about distribution, too. Some publishers, like O’Reilly, are their own distributor; they manage relationships directly with retail book stores and Amazon. No Starch, by contrast, uses Penguin Random House as their distributor. If you think your audience wants ebooks, self-publication or O’Reilly might be better. Consider traditional distributors if you care more about print copies.

If you’re willing to hustle, self-publication might be for you. You get more money per-book self-publishing, but you’ll have to figure out the Amazon marketplace, Gumroad, ebooks, print publication, editing, sales, taxes, and much more. Publishers handle all of this for you.

If you want to focus on writing, a traditional publisher is probably better. They’ll give you an editor, help with design and layout, and manage distribution. They’ll take more of a cut, though. Take a look at No Starch’s royalty agreement here: 15 percent royalty with no advance, 12 percent royalty with a $5,000 advance, or 10 percent royalty with an $8,000 advance.

Whether you self-publish or go with a traditional publisher, you can’t avoid marketing. Publishers just aren’t good at it. You’ll have to leverage your network, social media, blog posts, presentations, and conferences to get the word out (assuming you want to drive sales up; not all authors care to).

Don’t Fixate on Writing Tools

Dmitriy and I wasted a month fiddling with writing tools; don’t do this. Git, Google Docs, Markdown, AsciiDoc, Word, whatever. Pick one and get writing.

Most publishers tell you which tool they want you to use. O’Reilly has authors use their Atlas tool. No Starch insists on Word or OpenDoc, and give you a template to use. If your publishers don’t have a preferred tool or you’re self-publishing, pick something off the shelf and use it.

Establish a Cadence

Writing a book takes a long time. Dmitriy and I naively thought we would write the book in a few months. The first few chapters flowed easily, “At this pace, we’ll have a draft in three months!” But writing a book was a lot like shipping software: the last 20% took 80% of the time (two years, in our case).

To get across the finish line, you need to establish a cadence. Force yourself to write every (week)day, no matter what. Writing a book is a daily endeavor. Don’t fool yourself into thinking you’re going to write in spurts (during vacation, on a specific month, and so on).

I wrote first thing in the morning with a big cup of coffee. The pandemic also helped–it completely eliminated my commute. I shuffled into my garage every morning and got straight to work. I tried to write at least half a page no matter what, even if it was junk. Some days I got a page or two, other days almost nothing.

My co-author, Dmitriy Ryaboy, and I wrote greedily at first. We grabbed whichever section inspired us the most. Our publisher encouraged us to write front to back, so we wrote in chapter batches (1-3, 4-7, etc). Batching chapters let us write one chapter while we edited a separate one.

Speaking of co-authors, conventional wisdom cautions against having a co-author, but collaborating with Dmitriy was fantastic. We cleared each other’s writer’s block, fed each other ideas, and edited each other’s work. Having someone to talk through problems and spitball ideas with is invaluable.

One caveat: Dmitriy and I both had extensive experience with open source, so it felt natural to collaborate remotely (we’ve still never met in person!). Getting to a single voice was fine–we edited each other relentlessly. I can’t speak to co-authors in general, but Dmitriy and I clicked nicely. You should definitely have Dmitriy as your co-author. ;)

Get Feedback

As you finish draft chapters, get feedback. Feedback always came to us from the editor first. Our editor was technical enough to give good writing and high-level technical feedback.

Secondary feedback came from a pool of past and current colleagues and friends. We sent our reviewers chapters after we’d done several rounds of editing with No Starch. Most of our reviewers would take a few weeks to get back to us, but it was great feedback.

The last layer of feedback came from No Starch’s book reviewers. The reviewers were surprisingly thoughtful and gave a lot of criticism. Many of the reviewers had strong points of view that we didn’t always agree with. We set a lot of this feedback aside, but there were still points that caused us to tweak a few sections.

Learn to Write

I thought I knew how to write, then we got our first chapter back from the editor. I was taken aback by the amount of red ink on the chapter, and felt the edits made the writing dry.

After some reflection, I decided to give an honest effort to improving my writing. Three books were recommended to me: Strunk and White’s Elements of Style, Zinsser’s On Writing Well, and Stephen King’s On Writing. Yes, two books have (basically) the same name; yes, it’s confusing.

You absolutely must read On Writing Well. Zinsser’s book changed the way I write. On Writing Well gives practical tips, and also discusses higher-level concepts. Again, read this book.

Elements of Style is the canonical book everyone recommends, but I found it mediocre, dated. and scattershot. Given its short length, it’s still worth a skim, though.

Stephen King’s On Writing is a nice-to-have. It’s split into two sections: an autobiography and random writing tips. The autobiography is fun; King has had an interesting life. I didn’t read the second part because it looked like a worse version of On Writing Well.

Wrap Up

This post should get you to the point where you’ve got a book that’s ready to publish. There’s a lot more to talk about–fonts, layouts, diagrams, covers, marketing, sales–but those are best left to another post. Happy writing!

Notes

• Thanks to Dmitriy Ryaboy, Johnny Kinder, and Tom Hanley for feedback on early drafts.