RE:Q about documentation plans (was horrible situation)

["Kit Brown" <kit -dot- brown -at- comgenesis -dot- com>]

<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:

Background
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
included?

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

Tools
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
http://www.techwr-l.com/techwhirl/magazine/writing/effectivetechreviews.html
.

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...

Regards,
Kit Brown
Principal
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 - SEE THE ALL NEW ROBOHELP X5 IN ACTION!

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: http://www.macromedia.com/go/techwrldemo

---
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
http://www.techwr-l.com/techwhirl/ for more resources and info.