Author resource center
The editorial process
Welcome to O’Reilly! You’ve now signed a contract with one of our editors and are ready to begin writing your manuscript. But before you begin, we’ve outlined some important points about what to expect during the editorial process—as well as some useful resources you can refer to along the way.
The first step in the editorial process is a development kickoff call, which your assigned development editor will coordinate. The goals of this meeting are to:
- Get acquainted with your development editor (whom you’ll work closely with for the next several months)
- Review the vision for your book and its intended audience
- Review the authoring/development schedule
- Discuss workflow and logistics (e.g., early release, tech review, art creation, and authoring format)
Setting the schedule
Your contract dates specify delivery milestones, which are often two chapters, half of all chapters, full draft manuscript, and final manuscript. But regardless of your contractual milestones, we advise that you and your development editor set up a more detailed schedule outlining when each chapter will be ready. Your schedule dates are extremely important to us because many O’Reilly departments—production, marketing, sales, etc.—plan resources, events, and announcements according to your milestones. So the more concrete you can be with your delivery dates, the better we’ll be able to plan the release date and help build awareness for your title.
A note about advances
If you and your acquisitions editor agreed to an advance in your contract, your development editor will request these incremental payments once you complete the milestones described in your contract to your editor’s satisfaction.
The first thing you’ll need to do as you embark on your book writing project is to select a format in which to write. Then you should review O’Reilly’s style sheet and illustration guidelines (see below).
Writing format: Atlas and other choices
We allow you to write in whatever format is most comfortable and convenient for you. Most commonly, authors will write in Google Docs, Microsoft Word, or Atlas. Atlas is O’Reilly’s authoring platform, which allows you to write and immediately build print- and digital-ready outputs in EPUB, MOBI, PDF, and HTML formats. Atlas is powered by Git, which means you can pull down your repository and work locally and post your book to GitHub. Atlas supports authoring in DocBook, AsciiDoc (the most common format), and HTML. If you choose to write your book using Google Docs or Microsoft Word, your development editor will provide a template to assist you with styling common elements like headers, figure captions, and code blocks.
O’Reilly style sheet and illustration guidelines
O’Reilly maintains a house style sheet, which you should refer to for common style conventions. It’s a good idea to review it as you begin writing. But rest assured your assigned copy editor will ensure your manuscript aligns with O’Reilly’s style. The work of the copy editor is done a bit further down the line, during production.
Guidelines and specifications for illustrations can be found here—they include tips on file types, resolution, what kinds of figures we’ll redraw, and how to submit final art files and a figure list. You’ll also get a dedicated illustrator for your book who will touch every figure, ensuring it adheres to O’Reilly’s visual style. Our lead illustrator is happy to consult with you throughout the development process to advise on sizing, file formats, problematic elements, complex sequences, etc. We like to make the process as simple as possible to ensure the creation of figures doesn’t get in the way of your writing. So if you’re inclined to sketch rough figures on paper and snap a photo for us to render, please do so!
Tips for writing
O’Reilly’s editorial team has compiled some advice to help you manage your time, stay motivated, and generally write more effectively. Above all, keep writing. Our editors, copy editors, and production staff are here to help you with everything else.
Your development editor
Developmental editing is essential at O’Reilly. The unique value add of the development editor (DE) is that they know how to critically assess material that comes in from authors and shape it into content that is both high quality and useful to O’Reilly’s audience. DEs have the language expertise to present content in a consumable, learner-centric way; the project management expertise to deliver a steady stream of quality content to the market; and the communication skills to effectively collaborate with authors and other team members throughout the process. You’ll submit your chapters to your development editor as you write them. They’ll edit them at a high level, focusing on organization, clarity, cohesion, concision, flow, text-art integration, level of detail per intended audience, and length.
DEs are the gatekeepers of quality; their highest priority is to protect O’Reilly’s reputation for useful and excellent content by flagging content issues early, offering solutions to content problems, working with authors on revisions, confirming quality with external reviewers, and speaking up when they feel that a project or schedule needs additional help. DEs advocate for whatever is needed to produce excellent content.
You and your DE will work closely together as your manuscript takes shape. You’ll develop a cadence for meeting to discuss the book’s progress as a whole, recent rounds of edits, and any questions or issues that may come up along the way.
Specific responsibilities of your DE include:
- Developing your manuscript
- Communicating project status internally
- Performing project management duties, including keeping your book schedule on track, coordinating tech reviews, launching early release versions, and requesting marketing copy and book cover art
Technical review is a critical stage in the editorial process. Your development editor will send your manuscript to reviewers with various levels of experience to get feedback on the technical accuracy of your material as well as the clarity of explanations, the level of detail for the intended audience, and the breadth of coverage.
Roughly four to five tech reviewers are engaged, ranging from relative novices (we need people who are learning the material to know whether the book is effective) to subject matter experts. And they’re often a source for the praise quotes on the back cover of your book. Your editor will have a few reviewers in mind, but it’s also helpful if you can recommend some.
Tech review is typically conducted in three phases:
- First two draft chapters
- First 50% of draft chapters
- Remaining 50% of draft chapters
Typically, your manuscript is sent to tech reviewers after you’ve incorporated your development editor’s feedback. The tech reviewers will send chapters back to O’Reilly with their edits and suggestions (and often praise!), usually by marking up PDFs or Word docs or via email.
After reviewing your first few chapters, your development editor will work with you to come up with a plan for launching the book as an early release title on O’Reilly. It’s common for chapters to launch as an early release before going through technical review. Once your early release is live on O’Reilly, you can share and promote the link publicly (e.g., on social media or during talks or training courses). The cadence for updating an early release with new chapters and revisions to existing chapters is roughly every four to six weeks.
After you’ve incorporated your tech reviewers’ feedback, double-check your manuscript. Ensure there are no lingering to-dos and that you’ve used terms and font conventions consistently (e.g., didn’t use Ajax in one place and AJAX in another). Run spell-check, provide an inline reference to every numbered example, figure, and table, and number the figure files so that they’re consistent with their placement in the book. Completing these steps will help save time and effort during the production process. You should also now be prepared to send the original figure files to your editor if you’re writing in Google Docs or Microsoft Word.
Once you feel satisfied with the state of your completed manuscript, submit it to your development editor. Your development editor will quickly read it one final time and polish the narrative. They may send you some final queries, or they may send it directly to production—this will depend largely on the amount of editing that was required during manuscript development.
Now’s also a good time to create two lists of people who should review the final draft of your book. The purpose of this final draft review isn’t to solicit more feedback about the text but rather to prepromote the book and gather praise quotes for the back cover. The first list should include the names of people important to your topic who may provide back cover quotes. The second list should include the names of people who might help promote and evangelize your book via blogs, Amazon, LinkedIn, or elsewhere after it’s published.
Sending your book to production
Now your book will go to production for copy editing, art rendering, layout, proofreading, indexing, quality control, and printing. At this time you’ll be dealing largely with the Production Department, particularly the production editor assigned to your book. A summary of the basic workflow stages in the production cycle is here.
Advice on writing and working on multiauthor teams
You’re ready to start writing your book! So…now what?
The beginning is often hard. Your editor gives you an unfamiliar style sheet that contains dozens of rules, which makes you feel like you’re being inducted into a secret society or applying for citizenship in a foreign country. (Refer to all figures and tables in the preceding paragraph of text, capitalize A-level and B-level headings, don’t put tabs in code examples…) The blank screen staring back at you is also daunting. Even though you were thrilled about the book and fighting for your proposal only days ago, you still may find it difficult to get started.
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:
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.
Decide whether your chapters will have the following elements—if so, be consistent across chapters:
- Opening paragraphs that describe the content to be covered in the chapter—the what and the why—so readers have context for what they’re about to read (highly recommended)
- Exercise headings
- Formal or informal summary sections at the end of each chapter
- Formal = Has a heading titled “Conclusion” or “Key takeaways” or similar
- Informal = No consistent heading but in essence a section or ending paragraph that sums up the chapter and transitions to the next one
- Other consistent sections like problem sets, etc.
- O’Reilly tips, notes, and warning boxes
- Other boxes that aren’t “branded” as tips, notes, or warnings
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
Effectively engaging your readers
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?
“You’re about to start a journey where you’ll be visiting different planets. For each planet, you’ll need to design a plant. Your mission is to learn what type of roots, stems, and leaves will allow your plant to survive in each environment. I’ll guide you through by offering some hints.”
“This program is about what type of plants survive on different planets. For each planet, a plant will be designed. The goal is to learn what type of roots, stems and leaves allow them to survive in each environment. Some hints are provided in the program.”
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).
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.
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.
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.
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?
“Figure 2-7. The Properties window, as you would expect, lists the properties of the control you select. You can organize the properties by category, as shown here.”
“Figure 2-7. The Properties window.”
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
There’s nothing worse for a reader than staring down the barrel of a page full of dense, plain text. Even if the content is interesting, the reader’s brain will soon realize it’s immersed in a nonfiction book—full of facts and instructions—and start to seek distractions.
Change up your approach and make the process of reading your book easier by breaking up blocks of text with visual or illustrative elements such as bullet points, illustrations, sidebars, and code where it makes sense to do so. Your book’s topic isn’t simple to learn (that’s why you’re writing a book on it!), so ease your reader’s pain by making each page more welcoming.
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.