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.

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

How to be immortal

A prefatory comment here: This is a speech I gave to a group of writers and technical communicators in the Society for Technical Communication. While some of the examples in this speech are pitched to writing, it doesn’t really matter. You can be immortal anywhere. And while I don’t normally worry too much about saying this, I want to make it darned clear that this piece is copyright 2000 by me, John Hedtke. I’m proud of this one and I don’t want it passing into the public domain. So there.

I’m going to tell you how to be immortal.

There are several ways.

The first is to live forever. (So far, so good for the lot of us, eh?) The next, which is pretty similar, is to avoid dying. (I think we’re all aces on that one, too.) Inasmuch as both of these methods take time — forever is going to take a while, after all — I have a method that may be a little faster. It’ll still take a while, but when you’re immortal, you can afford to take the long view.

(By the way, one of the nice things about immortality is that the opportunity to be immortal is open to everyone. Everyone can be immortal if they want to. This is not a zero-sum game. Everyone can win.)

I’d like to add that, as I present my method to you, there will be several references to concepts developed in Roman times. This proves two things: one, the Romans had a great deal of the way life works figured out several thousand years ago, and two, the time I spent in college wasn’t for nothing… it cost thousands of dollars.

The basis for the third method of being immortal is doing your part of the Great Work. If you haven’t heard that term before, the Great Work is a mystic thing—you’re never absolutely sure that this is The Thing you should be doing, but it’ll usually fall into the categories of “I think so” and “It’ll do until something better comes along.” The difference between our jobs and the Great Work is the difference between vocation and avocation: what we do to keep the cats in canned cat food and what we do to make the world a better place.

There’s more to it than this as well: If each person makes their contribution to the Great Work, it brings us to the Roman concept of communitas, the health and well-being of the community. Communitas is not a zero-sum game, either; the greater the communitas, the better the members of the community will be. In fact, communitas is the antithesis of a zero-sum game: if one person wins, then everyone wins! Not only does the Great Work make everyone’s life that much better, but it’s something outside yourself, a vital element of immortality.

My contribution to the Great Work seems to be helping people get jobs. (As a way to participate in the Great Work, it’s not bad; I encourage you to give it a try yourself.) Someone comes to you in need, sometimes rather desperate need, and they need to find a job. The people who most frequently ask me about finding jobs are new folks. We’ve all heard (and all asked at some point in our careers, so we should remember what this feels like) “How do I get started?” and “Where can I get experience?” We’ve got some stock answers for this: training, certificate programs, and so on, but we’re not usually very good about this: we, after all, are looking for folks with 2+ years experience, some Word and/or FrameMaker experience, a technical background, but surely someone down the road might be able to, uh….? The people who have that 2+ years of experience don’t usually need our help a tenth as much as the new kids. The new kids are the ones who need us the most.

I’ve always felt that helping someone get a job was the best thing you could do for them. Lots of things go into this: coaching them on interview skills, helping them structure their resumes to sell themselves more effectively, getting them up to speed on a new software package that’s The Hot Thing, providing internship opportunities, even teaching them basic “Dress-for-Success” skills. You can also give them the hand up that they need by putting them in contact with the person who needs someone with precisely their skill set. They take your advice, they get the job they’re after, and voila! They’re no longer in need. They feel good and so do you. All of this takes a lot of time and energy, but that’s okay; this is my personal contribution to the Great Work and I like doing it.

Keep in mind that nobody ever got where they were in life without someone, somewhere giving ‘em a break they didn’t rightly deserve. We need to ask ourselves “How do we pass on what we know and what we believe and what we think should be done?” We’re award-winning writers and editors and artists; now that we’re so cool, we need to pass it on and complete the cycle.

There are a lot of different ways to extend your energy in the STC to help people get a leg up, including:

  • Being the local job coordinator
  • Volunteering to be hospitality officer or a hospitality deputy
  • Hosting a picnic for the new people in your chapter at your house
  • Posting job information to the chapter job line and the newsletter
  • Sponsoring an internship at your company
  • Teaching a mini-seminar on a special skill
  • Teaching people to write good resumes
  • Helping someone assemble a portfolio
  • Hiring someone for a very small contract assignment for which their experience is a large part of the pay

What you do doesn’t have to be done in the STC; it can be in almost any venue. (I know, that’s nigh unto blasphemy with this group, but it’s true.) Go talk to a class of wannabe writers — I’ve talked to English and writing classes in high schools about the joys and wonders of being a freelancer and a non-fiction author. Even Creative Writing classes will be interested. You can be the treasured memory of some high school student’s junior year. Volunteer to be a job contact for your college through their alumni office: Lots of people who are in college are interested in asking questions of people who are working in a field that they’re interested in.

Helping people get jobs has an immediate payoff: both of you get a good feeling right away. Suppose you’ve been doing this for a while and helping people get started, move up, and move on to new jobs and experiences. Three, four, five years later, you’ll be looking for a job yourself. And the people that you’ve helped find a job are out in the community working, possibly not at the same job, but they’re launched on their own careers and moving ahead. The people you helped in the past can tell you about jobs that they now have to offer or positions they’ve heard about from peers. And if nothing else, they can provide references about what you’ve done for them and others in the past. You get to network a lot and meet a lot of great people. That’ll feel good, too.

When you’re immortal, it brings a lot of other things into perspective and we’re able to identify what’s important and what isn’t. Our jobs aren’t the important stuff. Here’s a case in point: At one point some years ago, I’d added 5 books to my bibliography in about 15 months and I was talking to my agent about the difficulties I was having juggling my rather pressing book schedule and the need to spend time in my relationship. My agent clarified things for me by saying “You know, when they’re lowering you into the ground, nobody’s going to be saying ‘Wow, that Hedtke! He got all his chapters in by May 31!'” The stuff we pump out during the day is what we do and how we pay the bills, but it’s not the really important stuff.

As a matter of fact, the things we do in our jobs tend to be of extremely limited value. We’re in a profession that makes what we do transient and even ephemeral. The things we write and draw usually have a lifespan of maybe a year or two; sometimes even less—a mere moment to someone who’s immortal. For example, when I was starting out in this business many years ago, I did documentation for tax preparation software. I knew that my writing was of finite value: after tax day on the 15th of April (an annual tax day being another Roman concept, by the way, for those of you taking notes), none of it would be of interest to any but a handful of late filers. (I see a few of you here tonight.) The value in this regard of the things we do in this regard is building a corpus of work and experience, but the value of individual old pieces is pretty small. At this point, I’ve got nearly 8 million words published, in the form of 26 books and close to 200 magazine articles and heaven alone knows how many manuals and online help systems since 1984, and, like the chambered nautilus, all but the most recent simply serve to show how much I’ve grown.

What is important is what we do when we’re immortal. We have an idea that the future is something we can see, sort of. If we just squinch our eyes up enough and peer into the sunset, we’ll be able to see what’s going to be happening. The Romans, you see, believed that the future creeps up on you from behind. No matter how much you looked over your shoulder, you could never see it. Anything you see in front of you is just going to be a pale shimmery reflection of what’s coming at you, sorta like trying to navigate when you’re driving at high speed by watching road haze on a hot day. And that’s why we’re so frequently surprised by the future: we can’t see it. So it’s a good idea to start working on being immortal now because no matter how much you may want to, you cannot start being immortal if you’re dead.

20, 30, 40 years from now, I hope that you all will have careers full of satisfactions, awards, and recognition. This will be wonderful, but your true measure of fame, your success in life, your immortality, is measured in how much you have helped other people and are kept alive for it in their memories and hearts.

And that brings me at last to the real secret of becoming immortal: decades from now, you’re going to be remembered by dozens, hundreds, possibly even thousands of people who you’ve been able to help get a new job, break into a new career, or publish their first book, and thereby start the cycle all over again. They’ll remember you fondly for the help you provided without strings, the energy you added to their lives, and the opportunities you gave them. You made a difference.

That’s immortality.

And it doesn’t get any better than that.

Final thoughts on submitting a book proposal

You can occasionally get a contract by coming up with a killer idea, phoning a publisher, pitching the idea over the phone, and hitting the jackpot… but you’ll stand a much better chance of getting the contract you want with the right publisher by making a planned presentation.

Most publishers let you submit via email or their website, but it may happen that you occasionally submit a proposal via snail mail. This is most likely to happen if you’re including samples of one kind or another that need to be printed. If so, don’t make the publisher return copies of anything to you! Publishers are up to their collective eyebrows in submitted material of various kinds (this bunch of stuff is known affectionately in the industry as “the slushpile”) and they don’t need the hassle of returning anything. Assume that anything you send to them won’t be returned; marking printed copies in red ink on the front page with “May be discarded after review” makes their lives even easier.

Remember that you’re selling your idea and your abilities as an author to the publisher, so it’s important for your proposal to shine. Publishers respond best to an idea if they can see that you’re excited about it, there’s a marketing niche, and that you know what to do to bring the book to fruition. If you think of your complete book proposal as a job interview by mail, you won’t be far wrong. Make sure the proposal is dressed well and looks good when it first meets the publisher.

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.