RE: Creating a Documentation Kit (Long Response)

Subject: RE: Creating a Documentation Kit (Long Response)
From: John Posada <jposada01 -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 18 Oct 2001 11:34:49 -0700 (PDT)

> > ...I've proposed the idea of a documentation kit that
> > contains a MS Word template (this is an internal standards);
> > a how-to guide; and a pre-formatted Excel project spreadsheet
> > that will help team leads plan and track the progress of their
> > documentation. I'll be available to help plan the projects,
> > review drafts and provide editing support. The

Maybe I can offer some advice on how NOT to deploy these templates.

I'm involved in a project driven from the VERY top, with the mandate

- look at each process in a specific division of the company,
- examine each step of each process,
- make changes to the process in any way shape or form that will
streamline the process. This includes developing inhouse software.

I'm working for one of the senior project managers who is designated
to be one of the primary drivers of this initiative. So far, we've
redesigned 5 proceesses, developed and deployed software to
facilitate the new process.

There are maybe 10 groups, and I'm the sole writer on 3 of them, with
most of the others using 1 writer per group. My job is to document
the re-engineered process, including flow charts, process documents,
and software instructions.

This is all good, fun, effective, and highly visable in the company.

Now, the bad part. There is a group that is responsible for being the
central depository of all documentation for the groups. To make
matters simple, they created several templates which the writers use
to create and submit their documentation.

A few days before these templates are to be deployed, they announce
by email a conference call, to be attended by anyone who is using
these templates. (I find out same day) Along with this eail
announcement comes a zip file with 5 Word DOT files and 3 Visio VSS

What DOESN'T come with any of this is anything resembling
intructions, style guides, etc. Just templates.

During this conference call, they proceded to explain the templates.
The conference call lasts maybe an hour.

That's it.

Two weeks later, when material is starting to how up with the
templates being used in all kinds of ways, most of them not what they
anticipated, they make the remark that they cannot understand why the
variation...after all, they explained them during the conference

I know you said that you will include a user's guide with the
templates. Word of caution...X amount of time after you deploy the
kit, it will get forwarded from one person to another, kinda passed
down from generation to generation. During the time, the instructions
will no longer get forwarded with the templates. At that point,
people will wing it.

My suggestions...don't make the instructions as a separate document,
but instead, include all instructions and style information as hidden
comments right within the document. When the user is looking at
Section 1 and wondering what they are supposed to do with that
section, all they need to do is view the comment and they see it
right within the document. it also gives your authors a place to
enter their own feeback, personalizing the instructions to be
appropriate for their purpose.

Don't expect that the initial explaination or documentation will
answer all their questions and don't expeect to be contacted with
questions...many people feel that doing so is a proof of stupidity.

> > managers involved with this project are very enthusiastic
> > about the kit and getting their people trained on it.

Of source they seem enthusiastic. Part of their management evaluation
upon which their raises/bonuses are based includes how well they
embraced new ideas and concepts. In most cases, it is lip service,
especialy when time gets tight and it becomes a choice of making
product or filling out documentation forms, spreadsheets, or MPPs.

John Posada, Senior Technical Writer
mailto:john -at- tdandw -dot- com, 732-259-2874

Do You Yahoo!?
Make a great connection at Yahoo! Personals.

Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

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


RE: Creating a Documentation Kit: From: Susan W. Gallagher

Previous by Author: Re: Programs for Writing
Next by Author: RE: Creating a Documentation Kit (Long Response)
Previous by Thread: RE: Creating a Documentation Kit
Next by Thread: RE: Creating a Documentation Kit (Long Response)

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

Sponsored Ads