RE: Documentation planning (was Re: FW: Extreme Technical Writing )

Subject: RE: Documentation planning (was Re: FW: Extreme Technical Writing )
From: SIANNON -at- VISUS -dot- JNJ -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 10 Jan 2002 12:22:12

John Posada submits:
"Spend the first week writing something and getting it distributed. It
could be only three pages long. Why? Until everyone sees that you aren't an
idiot, they will be hesitant to appear associated with you."

I think you may be making a mistaken assumption here. (Correct me if I'm
wrong.) I should apparently clarify that at this point, no one has given
you a request for a specific document or document type. *They* don't know
what they need, and you are there in part to determine what their
documentation needs are (that is why I detailed the scenario description
the way I did).

Without knowing what the heck you're writing (is it a design document? a
help system? requirements? a troubleshooting or procedural manual for a
piece of hardware? a memo to say "here I am, look at me"?), how can you
write something that doesn't make you look incompetent, or like you're just
producing docs that no one needs to make it look like you're busy? I can't
figure out how "write first, ask questions later" can work in this specific

Now, if there is a solid deliverable established, sure, that sounds like a
reasonable strategy for establishing yourself. But writing something just
to show you can write still assumes someone will want to read it. If
there's no review process established, the audience(s) is not yet
determined, and the SMEs prefer to read unsolicited documents only if held
at gunpoint, you could be making yourself very unpopular doing that.

Kevin McLauchlan submits:
"When I took this job, 3-1/2 years ago, we got to that point you describe
before my *interview* was finished. I started work five days later (only
because my boss at the company I was leaving insisted on some handover to
my replacements), and I had a manual due for the end of the following

Man, it must be great to work with groups who not only have what they want
already defined, but give it to you before you've even accepted the job.
However, that was not the question posed here. Sure, these kinds of
situations can be avoided by insisting on a solidly-defined set of
deliverables from the customer before you agree to work with them. That is
a subject we've discussed before here (I was wistfully taking notes).

Not all customers are hiring TWs for specific deliverables, however. If
they are bringing you in to "manage our documentation", because they don't
hknow what they need, but they know what they have isn't cutting it, you
won't have that kind of guidance. That's what this question is addressing.
It isn't applicable to all situations, but it's not uncommon. I brought
this specific scenario up because I've felt that this list has occasionally
avoided addressing the issues of such "messy" jobs because many of the
members who post in detail are veterans of the industry who have learned
how to avoid such situations, so the discussion veers toward the goal state
rather than addressing the ingredients before us. We learn how to handle
the cake going into and out of the oven, what temperature and time to cook
it, and how to decorate it, but we don't list all the ingredients, or how
to combine them or refine them ("cut the butter into the flour, dearie,
don't try to mix cold butter into the liquid ingredients, and only include
the egg whites, reserve the yolks for later").

Basically, I'm asking for strategies for taking this kind of thing head-on,
as it is handed to you.

Just trying to clarify,

Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for FREE, through January 15th. RoboHelp can import your existing
Help projects! Learn how else RoboHelp can benefit you.

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.

Previous by Author: Documentation planning (was Re: FW: Extreme Technical Writing)
Next by Author: FW: Documentation planning (was Re: FW: Extreme Technical Writing )
Previous by Thread: Re: Glossary functions and features in elearning
Next by Thread: RE: Documentation planning (was Re: FW: Extreme Technical Writing )

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

Sponsored Ads