Author resource center

You’re ready to start writing your book! So…now what?

But eventually you decide which chapter to tackle first, expand your outline to include complete sentences and transitions, add some simple figures that support your explanations, and begin a long, smooth period of writing. Unless you get a new job or family demands crop up, this happy productivity continues about two-thirds or three-quarters of the way through the project.

That’s when burnout—both physical and mental—can hit. When you can see the finish line, but you just don’t seem to be getting there. You might get frustrated. What felt like easy, enjoyable work a few chapters ago is now an uphill battle. But we’re here to guide you along the way.

Once you get through it (and you will), you’ll reach that wonderful moment when the whole book is finished, and you’ll bask in the praise you get from tech reviewers and your audience. Those things make the whole process worthwhile.

Starting the book and overcoming the period of burnout are quite the tasks. The O’Reilly editorial team recognizes this. So we’ve compiled some hints to help you manage your time, stay motivated, and generally write better.

Beating writer’s block and burnout

Perhaps the most important advice on this topic comes from writer Neil Gaiman:

How do you finish [your book]? You finish [it]. There’s no magic answer, I’m afraid. This is how you do it: you sit down at the keyboard and you put one word after another until it’s done. It’s that easy, and that hard.

Most writer’s block falls into two categories:

1. Fear

Writer’s block often stems from fear: that what you write won’t be good, that you’re not “really” a writer. (Imposter syndrome is real.) This is where Neil’s solution comes in: just keep at it. Write when you don’t feel like it, write when your kids are upstairs monopolizing the iPad, write on a sunny spring day, write when your household is sleeping…you get the idea. Most of the time, just sitting down and deciding to write can help to get you into a flow.

A target word count is also a good motivational tool. Allocate a certain time each day or two to begin to write, and make yourself continue until you’ve reached the desired word count. (There are roughly 300 words per page in an O’Reilly animal book. Just FYI!) Sometimes this will take an hour; other times you’ll kill an entire Saturday morning. But a target word count will eventually speed up your pace and keep you from getting distracted, whereas a time limit might just find you surfing instead of writing.

Here are a couple of helpful resources for overcoming writer’s block and developing a routine for writing:

• O’Reilly author Mitch Seymour’s Medium post “Tips for Writing a Tech Book”
• Antony Johnston’s The Organised Writer (a personal recommendation from O’Reilly author Sam Newman)
• Tim O’Reilly’s expert playlist Learn How to Write a Great Technical Book, by Example

2. Not knowing the right thing to write

This is harder. You’re writing, but you just don’t know what to say.

Just write anyway. You can always revise, cut, or add, and your development editor is your best friend where that’s concerned. Just getting something done helps. (See Anne Lamott’s “Shitty First Drafts” for more on overcoming perfectionism.) There’s nothing worse than coming to the end of a day and still having a blank screen—you’d give anything to take back the wasted hours and have just written a page or two. Putting something down, good or bad, maintains momentum.

Avoid doing a lot of self-editing, searching for tons of feedback, or worrying about what everyone’s going to think while you’re writing your initial draft. It’s the first draft—of course there are going to be some mistakes. But it’s better to come back and deal with mistakes later than to rewrite a chapter five times when you still have 10 more to do.

In particular, don’t get hung up on opening sentences or paragraphs. This goes for any chapter, section, or sidebar. Just put any old thing down and come back to it later. Once you’ve gotten started, you’ll find that it’s much easier to keep going.

Here are a few more tips on beating writer’s block and getting into a flow with your writing:

• Start to write in plain text if you find the style sheet intimidating. You can convert 10 pages to the style sheet later without much effort (and it’s a good training experience). Just don’t let the plain text phase go on too long: conversion is very boring.
• You don’t have to start on the first page of chapter 1 and just plow through. If that works for you, great, but many authors start with a small, self-contained topic and leave the first chapter or two for later.
• Work with your development editor to start tech review fairly early. Not only is it good for the content, but it also provides you with a loose support group and some helpful comments to boost your spirits during the last sprint. Putting chapters into early release can also offer a lot of positive reinforcement.
• Tell clients, family members, and others that you’re starting on a major life project. Ask for tolerance (and perhaps even forgiveness) in advance.
• Prioritize your daily activities to make time for writing. Hold off on activities you can go without doing for a while. When you’ve publicly dedicated yourself like this, it’ll be easier to keep your mind on writing—and harder for interruptions to break your momentum.
• Leave optional chapters for last. Be willing to release the book without them. You can add them to your book’s GitHub repo or to other online resources later.
• Alternate between fun topics and tougher ones. A lot of "two-thirds of the way through" burnout is due to writing all the fun stuff first and leaving all the "laundry list" chapters for the end. Mix up the fun and the slogging if you can.

How to write well

We encourage every author to do four things:

• Read The Elements of Style.
• Read the second half of On Writing. Yes, it’s from Stephen King. And it’s generally considered to be one of the best books there is on writing.
• Read all of The Forest for the Trees. It’s an essential and enduring companion for new writers and a good read in its own right.
• Read your final draft out loud before submitting it to your development editor. You’ll be surprised at how much this simple practice can help improve your manuscript.

Try to avoid:

• Using a plethora of adverbs.
• Getting too fancy and not just saying what you mean. Mark Twain’s advice to James Fenimore Cooper applies here: “Use the right word, not its second cousin.”
• Telling rather than showing. This refers not necessarily just to text versus graphics but to explaining the why of something to your reader rather than just telling them the conclusion.

Don’t worry about these things to the exclusion of getting something down on paper though. Remember: just keep writing, do your best, and we’ll help you with everything else.

Books written by multiple authors

If you’re writing your book with multiple coauthors, you’ll need to pay special attention to things like consistency in style, formatting, level of detail, and redundancy in coverage. We’ve created a short checklist for multiauthor teams to refer to during the writing process:

Voice and style*:

• Are you all speaking directly to the reader (i.e., “you”)?
• Are you referring to yourselves as “we” (coauthor voice)?
• Are your chapter titles and section headings consistent?
  • How abstract or concrete are they?
  • Are they sentence-style or simple terms?
• Is your tone consistent across authors in terms of how formal or jokey you are?
• Are you using bullet points or numbering in your lists, and how often will you use them?
• Are your code blocks styled in the same way?
  • Atlas allows for numbering within code blocks. Please decide if you’d like to occasionally make use of that.

*O’Reilly copy editors will smooth out voice and style once the book goes into production. It will streamline the production process if you can agree on the basics listed here in advance (i.e., during writing and development), but know that an editor will do a final pass for cleanup. Also don’t worry too much about British versus US spelling and punctuation. Our copy editors will address that as well, bringing everything into the O’Reilly (US) style.

Chapter elements:

Decide whether your chapters will have the following elements—if so, be consistent across chapters:

Other things to look at in terms of consistency:

• Similar heading use in terms of wording but also the amount and levels of headings used (O’Reilly typically allows for four levels of headings.)
• The point at which the first heading is used (at the very beginning of a chapter, a few paragraphs down, or farther into the chapter)
• Bulleted or numbered lists
• Figure and table numbering (see the style sheet), the inclusion of figure and table captions, and in-text references to figures and tables to set context

You know your topic. But your success as an author is based on how well you can empower your readers to do things they were unable to do before reading your book. Below are a few ways you can get—and keep—your readers’ attention, as well as some things to avoid.

Some things to focus on

Use a conversational tone

Do you write like you talk or like you read? Don’t be afraid to use your speaking style when writing. In the words of writing expert William Zinsser, “Be yourself.” Using personal pronouns and contractions is a good rule of thumb. Write to your readers as though you’re sitting next to them having coffee, not lecturing to them from the front of the room. Studies have shown that a conversational tone compels readers to pay attention and retain information: engaging your readers is the first step toward empowering them.

For example, which of the following statements is more memorable to you?

The brain pays more attention when it thinks it’s engaged in a conversation because it prepares to respond. You want your readers to feel that learning is a collaborative experience, not a dictatorial one. Insert your personal style to enliven the text and compel the reader to participate.

Three great examples of O’Reilly authors who use an engaging writing style and conversational tone (all while teaching technical, complicated, and abstract topics) are Aurélien Géron (Hands-On Machine Learning with Scikit-Learn, Keras, and TensorFlow), Sam Newman (Building Microservices), and the team of Neal Ford and Mark Richards (see in particular Fundamentals of Software Architecture).

Be motivational

Focus on your readers’ needs: Why are they reading your book? What’s motivating them to learn about the subject? Is it to impress their boss? Succeed at work? Do their jobs more efficiently? Anticipate your readers’ objectives so you can approach the topic in a way that resonates with them.

Focus

What’s the one goal you have for your book?

The proposal guidelines asked you to state the goal of your book in one sentence. Put this goal on a sticky note and place it on your monitor. As you write, refer back to it frequently. Does each page of your book contribute to this goal? If not, trim the fat where necessary; if something isn’t critical to your readers’ understanding (e.g., a lengthy overview on the history of your topic), cut it.

Consider your main goal for the book, then break it down into a number of mini goals—one for each chapter. Identify the building blocks required to construct these goals successfully and make certain you’ve addressed each effectively. Be brave: leave out material that doesn’t contribute to each chapter’s goal.

Use visuals and illustrations

Many people are visual learners—our brains can process visual information far more efficiently than words. It’s why images are more memorable than text. Can you make your point visually? Use line art, screenshots, tables, or code with annotations to engage your readers, giving them a respite from too many consecutive paragraphs of straight text.

Redundancy

What do you do when you explain something to a colleague but he or she still doesn’t get it? You explain it in a different way. Take a different approach to get them to the same conclusion.

Redundancy does not mean repetition. Redundancy means conveying the same idea in an alternate way—using a different perspective or channel such as graphics, examples, or exercises.

Annotate code

Commenting on code inline offers insight without disrupting your readers’ flow. For instructions on how to insert these in your manuscript, see the production guidelines, which include specific instructions for the authoring format of your choice (Word, AsciiDoc, DocBook, etc.).

Use instructive, not descriptive, figure captions

Every element in the book is an opportunity to share your knowledge, and captions are no exception. Don’t waste the caption space stating the obvious; impart a bit more knowledge to your readers.

Which figure caption do you think provides more value to the reader?

Use scenarios

How many times have you opened up a book that starts with an overview? Boring, right? But what never gets old is storytelling. Consider this opening: “Your boss walks in and tells you he needs a new feature added to an application by the end of the day. You realize you’re in trouble: the guy who designed the application is on vacation. Now what do you do?” This type of scenario-based opening can really engage your readers. Scenarios provide a way for readers to internalize a problem and become invested in learning about the solution.

Some things to avoid

History lessons and overviews

Sure, history lessons can be interesting, but the information is rarely critical to understanding the topic. And overviews aren’t compelling because they don’t provide enough depth or instruction to be useful. Keep your readers’ motivation in mind and omit material that isn’t necessary for their needs.

Boring “Hello, World” examples

In your proposal you emphasized how your book is different. One way to make sure you maintain this truth within your manuscript is by using cool, unique examples—not the same old same old.

Too much text without visual breaks

This may all sound like common sense, but it’s actually hard to write so sensibly. Don’t worry. Your editor is here to help as you develop your manuscript.