RE:Q about documentation plans (was horrible situation)

Subject: RE:Q about documentation plans (was horrible situation)
From: "Kit Brown" <kit -dot- brown -at- comgenesis -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 17 Dec 2004 10:01:46 -0700

<snip> where can I find these documentation plans?</snip>

Like Peter, I always do a documentation plan. Here's a rough outline that I
use. Depending on the complexity and/or the doc experience of the project
team, I may add sections or explanations, as needed. Most of my plans are
less than 5 pages.

Doc plan:

Brief description (1-2 paragraphs) about what the project is, why you are
doing it

Purpose and Scope
What is the documentation supposed to accomplish? How big is it? What
outputs do you think it will require (print, web, online help)? What's not

Proposed Process
Describe who's doing what to whom and how often. Include number of reviews,
types of reviews, who the reviewers are with contact info. I recommend
"chunking" the content for the first reviews and identifying what's new. Set
expectations about completeness (e.g., draft 1 is 60%, draft 2 is 90%,
signoff) and for reviews. Include a consequence for non-response (will it
languish or will you just assume no news is good news?)

Proposed Schedule
Look at the overall project schedule and work with the project manager to
plan your reviews around their crunch periods. Regularly update this
schedule. If possible, get the PM to include the doc milestones in the
overall project schedule (gives more visibility and credibility); if
appropriate, include dates doc needs to go to localization

Content Model
Provide an annotated outline of what you are going to write about. I like to
include anticipated graphics and tables in this because it will help to
scope the graphic designer's workload

Tell 'em what tools you are using to produce the doc.

BTW, I wrote an article for TECHWR-L a couple of years ago on conducting
tech reviews. Here's the link

The plan will save you hours of time later in the project of justifying your
existence and in getting your stuff reviewed.

BTW, ALWAYS document who provided comments and save your backup and emails
at least until the doc is out the door. I had a similar situation where
someone insisted that they'd never seen a particular chapter and held up the
product release for a minor change (then tried to blame me for it). Luckily,
I had their signed reviews and showed it to them and my boss...

Planning and being proactive go a long way to short circuit evilness and
incompetence. BTW, my philosophy is that life is too short and no amount of
money is worth being in a toxic work environment. If you have done your best
to rectify the situation, get out as soon as you can. There's way more to
life than work...

Kit Brown
Comgenesis, LLC
PO Box 140092
Boise, ID 83714
+1 208.343.8706
kit -dot- brown -at- comgenesis -dot- com

"Practice random acts of kindness and senseless beauty"



RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo:

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Suicide threat--open letter
Next by Author: RE: New TECHWR-L Poll Question - Left or Right?
Previous by Thread: Re: Dilbert - English Degree
Next by Thread: Sorry Tech Comm Dood

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

Sponsored Ads