Re: I know I read that somewhere...

Subject: Re: I know I read that somewhere...
From: SIANNON -at- VISUS -dot- JNJ -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 21 Dec 2001 13:36:16

Susan W. Gallagher writes:
"I'm looking for the post that discussed installation instructions
for sys admins where the book showed lots of screens and the users
went by the pictures to install and missed a lot of decision points
in the text."

I'd be intrigued by this information, as well, due to a recent point of
amusement/aggravation I experienced recently:

One of our projects had been drowning the team so that we had no time to
address to this other, smaller project (an upgrade to an existing system).
The decision was made to give that project to outside contractors.
Concerned over whether the documentation they were producing was going to
meet our needs, especially since I'm going to have to maintain it, I
pounced on the (electronic only) docs as soon as we got them.
I was appalled at several things I found, but the one that amused me
was the installation guide they created. It showed screenshots of the
installation wizard, but no accompanying descriptions to indicate what
configuration parameters or other data to enter into the respective
screens, and the only screenshots that included text (to specify
installation locations) included false/invalid text. If this was an
external product, I could understand the bogus text IF THEY NOTED IT AS AN
EXAMPLE. But (a) it is an internal product, designed and built to be
installed in a specific, known environment and location, and nowhere else,
and (b) they didn't give sufficient description of any of the steps to
indicate the false text was an example, and not an expected default value.

....a picture may be worth a thousand words, but if they aren't the *right*
words, there can be a problem.


Shauna
(who will be re-doing the docs we received to match the formats/structure
we wanted, and filling in missing info. as needed. *sigh*)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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


Previous by Author: Re: The three great virtues of a technical writer
Next by Author: RE: "baseline"
Previous by Thread: I know I read that somewhere...
Next by Thread: Portfolio


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


Sponsored Ads