Documentation plans–Appendixes

There are three appendixes that typically show up in my documentation plans:

  • Author resume
  • Audience analysis
  • Terms of agreement

The author resume appendix is just that: it’s your resume. You’ll include this whenever you’re using the documentation plan to pitch a job: freelance documentation contract, a book with a publisher you’ve never worked with before who needs to be sold on your qualifications, or your response to an RFP. If you include this, have a cross-reference in the Overview section where you mention the author names so they know to look at this appendix to see your resume and thereby appreciate you more.

The audience analysis appendix is an expansion of the basic audience information that appears in the Overview. There’s a lot of stuff you might put in this section, including personas, audience surveys that profile the readers, or even marketing info (although when I’ve got that much marketing information, I usually build a separate appendix for marketing info).

The terms of agreement appendix is only used when you’re using the documentation plan as the primary statement of work (SOW) for a freelance writing contract. For the terms section, you’ll put the responsibilities and assumptions from the overview, the description of deliverables from the production information section, and any conditions for renegotiation.

Documentation plans–Detailed outline

The detailed outline is an outline done as deeply as you can. Chapter titles and three levels of heads within each chapter are par, but I’ve had a few cases where I wanted to go deeper (and did). The more detail you can get into your outline up front, the better estimates you can make and the clearer picture you’ll have of what’s in the book.

List everything in the detailed outline, including every bit of front matter, chapters, appendixes, glossary, index, coupons and ads for the back of the book, and possibly even back cover text.

Use heading styles for your headings, because you can then collapse and expand levels in Word, reorganize, and change your style formatting quickly if you need to.

Put descriptive comments for most headings. Each chapter should have a sentence or two describing what the chapter is about, as should each major heading in the chapter. I use a Heading 7 style for that’s been indented two inches and is in a small font. I could use a text style for this purpose, I’m sure, but I just have gotten used to this over the years.

If you have multiple authors or contributors, each chapter heading should list the name of the person writing the chapter in [brackets]. If a different person is writing an individual section within a chapter, put their name in [brackets] next to the relevant heading. If you have a lot of source material experts involved with the project, you may also want to list their names next to the appropriate chapter titles or heading levels.

The detailed outline is a living document that will change over the course of a project. On my first book, I used the outline as part of my completion ritual: each time I finished a chapter, I replaced the chapter’s outline as I’d planned it with the outline of the actual chapter I was submitting. The actual chapter was certainly more detailed than what I’d scoped out, but it was interesting to see the variance between the two. If you end up with a 75% overlap between what you planned and what you wrote, you’re doing well.

Documentation plans–Schedule

The schedule section answers the “When?” questions.

Enter the project schedule here. Have as many benchmarks as possible. You may take this down to the “Chapter 1 out for 1st review/Chapter 1 back from 1st review/Chapter 1 out for 2nd review…” level if you wish, but in my experience, it’s not desirable to be that detailed because any time there’s a single slip, you have to recalculate everything. On the other hand, if you’re doing something with multiple contributors, it’s a very good idea to track the individual pieces they’re doing so they don’t get lost in the shuffle. (In a case like that, I might suggest having a medium-detailed schedule here and then use a spreadsheet during the project to track the specifics for each person.)

For the purposes of a documentation plan, though, a two-column or three-column table of phases and dates is quite adequate. Be sure to include the project start, the production dates, printing dates, and the like in the schedule. You may have other benchmarks for an ebook, a print-on-demand book, or a CD/DVD that’s included with the book, such as preparation of master files, approvals, reviews, and release to the duplicator or distributor.

If you have no other dates lined up, you might use the following list as a baseline and take it from there as the project requires:

  • Writing start
  • Handoff of initial TOC and first chapter.
  • 25% ms. complete mark.
  • 50% ms. complete mark.
  • 75% ms. complete mark.
  • 100% ms. complete mark.
  • Production and page proofs complete; book to printer.

At the end of the schedule, always include the following statement: it’s a good, general-purpose escape clause.

Note: This schedule assumes that the scope, purpose, and outline in this documentation plan are substantially correct, and that no time will be lost due to sickness or other delays. Any changes to these assumptions will result in a comparable, day-for-day extension of the schedule.

In other words, if they’re late, you’ll be late, too; it’s not your job to make up the slack for their lack of process. If you manage to sell this to management effectively, be sure to tell me how you did it.

Documentation plans–Staffing

The staffing section answers the “Who?” questions.

Several tips about this section:

  • When you have lists of names, such as for reviewers or testers, list people in alpha order so it’s clear you’re not making a judgment on their relative worth to the project.
  • Names can and frequently do appear in more than one section. Someone responsible for approval is certainly also going to be a reviewer, possibly a tester, probably a source material expert. The project editor may also be the copy editor, the proofreader, and the production coordinator.
  • If you have a lot of names in a section, consider building a table to show who’s doing what.

Author(s) Enter the names of all the authors and contributors and the chapters/sections they’re responsible for. If you have a lot of authors, make a table.

Project Editor Who’s coordinating the editing? This is the person you’re going to be dealing with at the publisher, so they’ll tell you who it is.

Copy Editor Who’s doing the copyediting? Usually determined by the publisher.

Proofreader Who’s doing the proofreading? Usually determined by the publisher.

Indexer Who’s doing the indexing? Usually determined by the publisher.

Designer Who is designing the book? Always determined by the publisher.

Production Coordinator Who’s coordinating the production?

Layout Will there be a special layout person? Usually determined by the publisher. If you’re responsible for layout, put your name here.

Art Coordinator Who’s coordinating any outside art issues? Always determined by the publisher.

Graphic Artist Who is doing the graphics? (Depending on the project, you may also have an illustrator or photographer.) Usually determined by the publisher.

Source Material Experts Depending on the project, you may want to identify your source material experts up front so they can budget their time. This can also be done as part of the detailed outline, listing the SMEs for each chapter or section.

Reviewers For books, the publisher will frequently identify someone as an outside reviewer, but most are willing to look at people you suggest. For a document, you’ll want to pick the internal reviewers based on who has a hand in the thing you’re writing about. If possible, get reviewers for overall content and style, technical accuracy, and standards and format. Reviewers can appear in more than one category.

Testers Enter the names of the people who will be testing what you’re writing. Not everything requires testing, of course, but a lot more requires testing than you might think. For example, everything in any how-to/DIY book on any subject needs to be tested. There have been cookbooks that weren’t 100% tested that had errors in the recipes that made them unusable (and really unpleasant).

Individuals Responsible for Approval You may not need this section for a book, but you will if this documentation plan is for a technical manual. Enter the one and only name in each category who is the final signoff authority for each type of review (as described under Reviewers). Never let yourself be approved by a committee; your spleen will implode during the process.

Instructors If this is a project for a specific group of instructors, you may want to list the instructors by name here.

Documentation plans–Production information

The production information section answers the “How?” questions.

What are the project deliverables? Give a brief description of the deliverables. The details for the deliverables are listed below, but if you say “1 printed manual and 1 companion CD of software,” the client can’t come back and say “Where’s the website that was supposed to be part of this?”

What are the writing and editing standards for the document? I use a boilerplate sentence that says “This book will follow the standards stated in the Chicago Manual of Style as well as any style considerations of [publisher’s/client’s] style manual.” You may prefer a different style guide, but this lets you nail down the final authority on the subject.

What format(s) will this document be available in? Identify the size and format for the finished product, such as standard 7-3/8″ by 9-1/4″ perfectbound trade paperback, 3-ring 8-1/2 x 11″, Kindle-formatted ebook, or whatever.

How many pages will this book/document have? Give a page estimate based on your outline. If you’re writing a manual for something, you may not have a limit on the number of pages you can have, but most books have specific page counts that they have to meet. For example, when I was coauthoring “The Complete Idiot’s Guide to Disaster Preparedness,”, the book had to be between within one signature of their typical page length. (We ended up cutting two chapters from the book to meet the page length, as a matter of fact.)

Even if you don’t have hard and fast limits on the size of a book or document, estimating the book’s size is an important statistic for estimating the time necessary for production, costs, and so on.

Are there special art requirements? “Art” is anything that isn’t text. It can be screen captures, conceptual art, sketches, line drawings, illustrations, photos (both B&W and color), or (if you’re doing something online) JPGs, GIFs, and videos. You may not have to do these yourself, but you’ll definitely need to identify what goes where.

What will the layout be? Most publishers have the layout predetermined to meet their stylistic considerations, but if there’s something you want for this book, mention it.

What kind of typesetting will there be? Again, typesetting is usually up to the publisher (although you’re expected to code and format your manuscript files appropriately). But if the answer here is only “Using Microsoft Word 2007,” you should identify this. If there are standard templates, mention those as well.

Will there be any layout requirements? This is usually handled by the publisher but if you have a book with, say, lots of photos that requires a non-standard layout, it should be noted here.

Who is coordinating the production? This is virtually always handled by the publisher unless you’re doing a packaged book for someone. If you’re working on a document for a company, this is more likely to be someone internal or even you.

How many copies will be produced? This is only relevant if you’re producing a printed book or document, but it’s the kind of information the production coordinator needs to get printing quotes.

How will this be printed? Who’s doing the actual printing, and how? Here’s where you’d mention anything about color separations, photo prep, and so on.

What will the cover art be? Who’s doing the cover art? What requirements for the cover art are there? Again, the publisher almost always handles the cover art, but you may have some input on what it looks like, as well as the inclusion of snipes on the cover and so on.

If you’re doing an ebook or a print-on-demand book, there will be additional production information considerations. For example, ebooks are likely to require special formatting in the file and print-on-demand books may require some additional coding or specifications for a PDF file. Mention that in this section.

Also mention if there are related materials that need to be produced. For example, this project might require a note card on special stock or a DVD inserted in the back of the book. (Publishers tend not to do this much anymore because the additional costs of inserting a CD or DVD are considerable compared to the cost of the book and downloading even huge files is no longer much of an issue thanks to cable modems.)

Documentation plans–Marketing information

The marketing information section answers the “Why?” questions. This section is important for book proposals, but if you’re working on some document for a company, you may not need this section. After all, they know why they want to do this; that’s why you’re working on it.

Why write this book? What need does this book fulfill? Where is the perceived hole in the market that this book will plug? You might have a great idea for a book that sounds like fun, but there has to be an identifiable market need for the book that will motivate people to buy it and read it. Sadly, I’ve proposed a number of books (most of which thankfully did not get picked up) that would’ve been a lot of fun to write but would have been a solution with no matching problem.

What’s the competition like? Even if you’ve got a great idea for a book, it doesn’t do you any good if someone published the same or similar book three months ago. List the books that are currently in print that are or could be competition and why this book is better than any of them, or at least what it offers that they don’t. This may simply be the freshest thing on the market or it might be a book that a publisher can offer in their line to match up with another publisher’s similar lines. Everyone comes out with a new book on Microsoft Word, everyone comes out with a basic cookbook every so often, that sort of thing. (BTW, every author I know does their research for this on Amazon. You can identify sales rank, publication date, and so on. In fact, knowing your competition’s publishers will help you avoid the publishers who have just published a book like you’re like to write.)

What marketing strategies should we use? What marketing strategies are of note for this book? Will this document have any major function as a marketing piece (for example, will this tutorial also be used for a marketing piece to sell new customers on the product)? Fill out whatever may be relevant for marketing information.

Are there special marketing considerations? Are there special marketing considerations, such as product tie-ins, plugs on TV shows, websites, forewords, endorsements? Can you get someone with name recognition to do a back cover quote? Did you go to school with someone famous you’ve kept in touch with? (I was at Reed with Steve Jobs, which sounds cool but in fact I didn’t know him.) What about a cover snipe to show that you’re an award-winning author? An Oprah book club sticker? (Hey, it can be done!)

Documentation plans–Overview

The overview answers most of the “What” questions.

What will this book or document be called? Everything is a potential point of contention, and that includes the mere name of a book or document. I’ve witnessed shouting arguments about whether a document should be called a manual or a guide. (I just sat back and watched for 20 minutes while these folks went at it.)

Who is the author? If you have multiple authors/writers/contributors, list all of them.

Note: If the plan is part of a sales proposal, or you’re using it as part of a response to an RFP, or you’re just pitching a new publisher you’ve never pitched before, you may want to put your resume in an appendix.

What type of book or document is this? Likely answers for technical non-fiction materials include tutorial, self-study guide, training materials, reference, combined tutorial and reference. Other possibilities are cookbook, travel guide, biography, journal, history, collection, and so on. You’ll have a good idea of what you’re writing already. Note that the format of what you’re delivering (printed book, ebook, DVD, online help, etc.) is covered in the Production section.

What is the book or document’s scope? Give a brief summary of what’s in the book. The elevator speech you used in your cover letter is perfect for this.

What is the book or document’s purpose? Describe the overall purpose of the book or document.

Who is the book or document written for? Describe your target audience: “The reader is someone who wants to find out about what cooking was like in other ages and who wants to try some of the recipes used in other cultures.” “The reader wants to plant a garden in their backyard to grow their own food and be as self-sufficient as possible.” Note that there may be several different types of readers, such as a main audience of raw beginners and a secondary audience who already know some of the material and want to see how they can improve. Describe each of these types of readers so you know who you’re writing for.

Note: It’s acceptable to put a summary of your audience information in this section and then add detailed audience analyses, such as personas or user-survey data, in a supporting appendix. Not all of my book proposals have this, nor my document plans, but if you’re pitching an idea that’s new or interdisciplinary, you’re going to need to show more about the reader than you might otherwise.

What is the average user’s background? “The reader can already perform basic cooking skills and is able to successfully read and follow recipes, but they have not mastered more complex cooking skills such as deboning a chicken, baking bread, or making a pie crust.” This may be a bullet list if you have a lot of skills. Again, if you’re dealing with multiple readers, describe the skills and background of each type of reader.

What will the reader get out of this? If the reader went through this cover-to-cover, what would they have learned to do at the end? List every thing that they’d learn in the course of the book. If you’re not sure what to do, leave this blank and come back to it as you put your detailed outline together. The goals for the reader tend to come from the 2nd- and 3rd-level headings.

Are there related projects? This project might dovetail with another book, a software release, the next Academy Awards broadcast, a new cooking show, or the Blue-Ray release of a movie. List anything relevant.

What are my responsibilities? List your responsibilities on the project, such as writing and reviewing content, working with the editor, doing any necessary screen captures, coordinating for photos and other artwork, and so on. Also list the responsibilities of any other writers and the publisher or client, both to nail down what they’re supposed to do and to make it clear in some cases that you’re not the person doing whatever that particular task is.

What are the general assumptions for the project? I always add a boilerplate assumptions section that says that I’ve described the project accurately in the Overview section of the documentation plan, that there won’t be any project changes that expand the scope to the point of breaking the schedule, that I’m not going to get caught in an endless cycle of reviews and edits (that one’s mostly for clients with a decision-making disorder), and that once they’ve had the nominally final version of the document for 10 days and they haven’t squawked, then their silence means they bought it as-is (again, for clients who might want to get cute about not paying for something).

If you are writing something that has training materials, you should also mention the environment and media that the training materials will be presented in and comments about the instructors’ style and background.

Documentation plans–Executive presentation

The executive presentation has an executive summary and a summary outline.

The executive summary is a quick, 2-4 paragraph summary of the project. Think “elevator speech” for this, making sure that you cover the 5 W’s and H. This is a short (absolutely no more than one page!) synopsis for the executives that read this who won’t want to dig through the details.

The summary outline shows the chapter titles, but nothing more detailed than that. If you have chapters grouped in sections or parts, show those, too.

Documentation plans–Front matter

The front matter includes the title page, a table of contents, and a change log.

The title page includes the book or document’s title, the last revision date (so people know which version of the plan this is), and the contact information for the lead writer(s) on the project.

The table of contents lists the various sections. A good documentation plan can be as many as 25 pages, particularly if you have a very detailed outline. I have occasionally done documentation plans for books that include resumes for me and my co-author at the very end as well, which also adds some bulk.

The change log lists every change you make to the plan so you can maintain your project history. Make an entry in your change log that describes what the change was and when you made it. You should also update the last revision date on the title page. Keep your project editor and other staff informed of whenever you’ve made a significant change to the plan as well. (This is a level of project management that most project editors appreciate in an author.) Trivial changes should be logged but you don’t need to re-release the documentation plan just because you added a few words to a description.

If this documentation plan requires approval, you may also want to have a signoff form on the front saying that the person has read the plan and approves it.

Understanding the sections in a documentation plan

A typical documentation plan contains the following sections:

  • Front matter
  • Executive presentation
  • Overview
  • Marketing information
  • Production information
  • Staffing
  • Schedule
  • Detailed outline
  • Audience Analysis (optional)
  • Author resume (optional)
  • Terms of agreement (optional)

The front matter in a documentation plan is actually several parts: the title page, a table of contents, and a change log.

The executive presentation is an executive summary and a summary outline.

The overview contains information about the scope and purpose of the project, the goals, and the relationship to other projects.

The marketing information section discusses the marketing justification for the project, marketing plan, and any special marketing considerations.

The production information section describes what the finished project will look like, what artwork is required, and printing/ebook and distribution information.

The staffing section lists who will do the various tasks, who will review the document, and who will approve it.

The schedule section identifies when each phase of the project is due, along with any assumptions that went into determining the schedule.

The detailed outline is an in-depth outline of the book or document.

You may have optional sections as appendixes. If you have a detailed audience analysis such as personas or extended information about the audience(s) for this document/book, it’s a good idea to have an appendix with your supporting information and analysis. If you’re using this as a sales document or bid proposal, you may also want an appendix containing your resume. And if you’re using the documentation plan to describe a piece of contract work, you may also want to have a section listing the terms of agreement, which describes who will be responsible for which pieces, what the handoff is, and the assumptions on which the plan is based.