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.

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>