Re: Documentation Plan

Subject: Re: Documentation Plan
From: Herv Peairs <herv -at- GRADIENT -dot- COM>
Date: Wed, 16 Oct 1996 15:54:28 -0400

Hi Misti,

In general, I find doc plans to be good for working out the doc design and
for keeping track of myriad details.

Here are some suggestions (not meant to be comprehensive):

* I have found a doc plan is a good way to get some basic assumptions
reviewed early on. I suggest including:

- reasonably detailed customer (user) population profile

- product description (a couple of paragraphs) that includes a description
of the problems that the customer will be solving with this product (in
other words, the reason they're buying it).

- specific documentation goals.

All of this can generate some interesting discussion in your doc plan review
meeting, especially if, say, product marketing and engineering weren't
already seeing eye-to-eye on these points.

* In the context of your doc goals and customer profile, provide a
high-level doc design discussion. What components will the doc set contain?
What will they contain. Will there be any quick reference pieces? What
will be online and what will be hardcopy? What online formats will you use?
Justify decisions based on your doc goals and customer profile.

* Define the physical parameters for hardcopy components, for example:
cover stock, paper, printing method, binding method. Cost it out if it
seems appropriate. If you work in a seat-of-the-pants company, this can
save you some gotcha's in the end game.

* Define the doc team and their responsibilities, including writers,
reviewers, artists, and editors.

* Define the sign-off process, if you have one (sign-offs, bleagh).

* Unless you are a consultant/contractor, I see little benefit in including
more than a cursory outline that defines doc component contents in general
terms. A long outline can be distracting or off-putting to your doc plan
reviewers. You don't want them to get bogged down in the outline -- you
want them to *think* about your design and the reasoning behind it. Anyway,
the way I write, the outline usually changes. :-)

* Be careful about putting schedules in doc plans. If you provide a
schedule, keep it coarse-grained and tie it to such milestones as functional
spec completion, availability of working product to play with, and review
copy returns. Don't include dates unless you have a good reason (which of
course you may).

* Hold a doc plan review meeting! I have found these to be extraordinarily
useful. People who will give you good, creative input, especially
engineers, tend to like the design phase best, and will reward you for
including them with lots of good ideas.


Herv Peairs
herv -at- gradient -dot- com
508-485-5235 x204

Previous by Author: What manual users want
Next by Author: Writing vs. ??? TECHNICAL writing: Sinners in the Hands of an Angry God
Previous by Thread: Re: Documentation Plan
Next by Thread: Documentation Plan

What this post helpful? Share it with friends and colleagues:

Sponsored Ads