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.

Why you really should plan projects

All of the reasons for planning in the preceding post are summed up neatly by Magid’s Law:

“It doesn’t matter how you get there if you don’t know where you’re going.”– Paul Magid

Paul Magid is one of the Flying Karamazov Brothers and coined this profound bit of wisdom 30 years ago. It’s the best justification for planning I’ve ever heard.

That’s all I need to say about this.

Why you should create a documentation plan

There are a lot of good reasons to create a documentation plan. The first and most important is that the documentation plan states the projects goals. The documentation plan also specifies the project details and describes the process for accomplishing the project.

A documentation plan answers the following general questions:

  • What do you want to write?
  • Why do you want to write it?
  • How do you want to write it?
  • Where will the document be written and produced?
  • Who will do the work?
  • When will they do it?

You’ll recognize this immediately as the 5 W’s and H.

Writing effective documentation plans

On my first technical writing job in 1984, Linda Jaech, my first doc manager (and a damn good one!) taught me how to do a documentation plan. It was a profound part of my education as a writer; thinking about it, it may have been the single most important thing I ever learned about technical writing.

We printed our documentation plans back then on a Diablo 630 daisywheel printer (a name which will make all the old-timers who read this nod their heads and go “Uh-huh!”). I used the format for the projects I did at that company, then for contract assignments, and then when I was doing my first book proposals. (I’d print those out at home on my Juki daisywheel, a noisy little printer that was nevertheless very, very good. And it worked exactly like a Diablo 630.)

Over the years, I’ve updated the format, but apart from the addition of some items and sections and the vastly improved formatting available with a laser printer, it hasn’t changed much. I still have a printed copy of the documentation plan my first Microsoft manual from 1986 and, apart from the limited formatting you can do on a daisy wheel printer, it’s clearly the same format. I’ve used this format for well over 100 manuals and writing projects and maybe 40 book proposals, a couple of dozen of which have been published. The format is adaptable and easy to use. I think that’s pretty cool.

This series of posts is going to show you:

  • why you should plan
  • the sections in a documentation plan
  • an analysis of the individual sections
  • where to get a copy of my blank documentation plan template

Documentation plans–Part 2

There are six basic sections of a typical documentation plan:

  • overview
  • marketing
  • production information
  • staffing requirements
  • schedule
  • outline

Note: You can use the same general structure for documentation plans for contract writing assignments, manuals, or online help. The information you include varies depending on the type of writing project, but the overall format is the same.

The overview section states the scope and purpose of the project, defines the audience, gives the relationship to any other projects, and identifies the responsibilities of you and the publisher. It also identifies the general details for the handoff of the finished product (how many copies and in what general form). What you put in the overview is not a binding legal description unless the information is included by reference in the actual publisher’s contract (some publishers may want to do this), but it spells out a lot of details that might otherwise get lost or misinterpreted.

The marketing section identifies ways in which the book can be marketed. (Most publishers don’t expect authors to lift a finger to help them market, so showing that you’re able and willing to supply marketing opportunities may impress them.) Be sure that you can also point to the competition in the field—no publisher wants to walk into a heavily populated field without warning—and how and why this book will beat all of them. Also mention if there are opportunities for co-marketing or bundling with the product. Dan Gookin’s classic book DOS for Dummies was already a bestseller even before Microsoft bundled it with their MS-DOS 6.2 release; in its day, there were millions of copies in print. Riding on a product’s coattails will help you, and can frequently help the product, too. Don’t be afraid to aim high with your marketing ideas.

The production information section discusses what the finished product will look like, and how you intend to get there. What style will be used for the book? What format and page size? Art requirements? Some of this is dictated by the publisher, but you should be able to estimate the number of pages and the type and approximate quantity of illustrations your book will have. You’ll probably also have an idea of what the book should look like overall, so mention this in the proposal.

The staffing section discusses who will be doing the reviews and which kind. It also identifies the technical editor (usually a reviewer with background in the field you’re writing about), illustrator, proofreader, indexer, and other related personnel. At the beginning of a project, most of these are likely to be unknown.

The schedule section lists the proposed schedule along with any assumptions about the schedule. Be as specific as possible. Budget for vacations, holidays, and life requirements (such as doing taxes, birthdays, and so on). Leave yourself as much room as you can near the end of the book to make up time—there’s never enough.

Finally, the outline section presents an in-depth outline of the book. A detailed outline is a requirement for a good book proposal! The editor can clearly identify the focus of your book and offer specific suggestions before you begin writing on how to change or improve the book to better fit the publisher’s marketing plans.

By the way, a documentation plan is best when it’s a living document. As a project progresses, you should make changes to the plan to reflect changes in staffing, schedule, or (most importantly) the outline. Whenever you make a material change, you should also send a copy of the revised documentation plan to your editor so they’re up to date as well.

BTW, don’t worry if this seems a little unclear to you. This is a brief discussion of the general information you need in a documentation plan. If you have a format you like that covers this, then you can use it. If you don’t or you’d like to try something else, I’m going to be posting a detailed series on how to create a documentation plan, including information on how to use it and a downloadable template, as soon as I wrap up this set of blog posts.

Documentation plans–Part 1

The documentation plan is a useful and necessary project management tool before, during, and after a project. It presents information about the book’s scope, purpose, target audience, and goals, the book’s market niche, the standards and styles the book should adhere to, staffing requirements, the delivery schedule, and a detailed outline.

At the beginning, the documentation plan gives detailed information about the project to the publisher so they can make an informed choice about whether or not they want to publish the book. Once your idea has been approved, the plan serves to further clarify your and the publisher’s concept of the project. By writing down and agreeing to the scope and purpose, the goals for the book, and the schedule, you eliminate most of the causes of friction between you and the project editor.

During a project, a documentation plan is an effective scheduling and tracking tool. With each of the sections identified, you can gauge your progress compared to your original estimates. This information is helpful for avoiding writing crunches near the end of a project. With the schedule and outline information, you can also use the documentation plan as a tool for delegating sections of a project to subcontractors or other authors on the book.

Finally, the plan serves as a reminder of the scope, purpose, and goals of a book, a standard against which you can check your work. A documentation plan is essential for a post mortem analysis of the project. You can check your original assumptions and statements of the project against the finished product. By comparing your actual schedule against your estimates, you can pinpoint problems to avoid or plan for in the next project. This information is extremely valuable, as over the course of several books, you’ll learn how to estimate your time in each phase of a project very accurately. This can result in tighter schedules, which in turn can help you plan for more book contracts.