Best Writing practices

Subject: Best Writing practices
From: Sandy McDonnell <sandy_mcdonnell -at- cmsinc -dot- com>
To: "'TECHWR-L'" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 9 Feb 2000 08:54:45 -0500

> When you can tell that information is missing, you have the
> chance to find that information in another way: There's a
> problem, but you know to correct it. You're really in trouble if
> you don't even know there's a problem.
[Sandy McDonnell] I think that's a pretty broad generalization. I'm
working with a versioning product that has a user guide that is incredibly
lacking. The information covered is often incorrect and there is a host of
missing information. The fact that the information is missing became
immediately apparent -- and as I dig I find more and more cases where
information is missing. The fact that I can see this doesn't mean we don't
have a huge problem. We may even choose to scrap using the product based on
this. I've been trying to fill in the holes in the documentation just so we
can use it and I've had to do the same level of research as if I were
documenting a product from scratch without the benefit of a functional spec
or access to a developer (I tried tech support and had to explain to THEM
how the product handles your files!).

I will say that to some degree, this gross lack of information was
"hidden". By that, I mean that upon a quick perusal of the User's Guide, it
looked fine. It was only in attempting to actually use the product (or even
structure the directories) that it became obvious. Had the person who
researched it (no, not me) gone further with it, perhaps we wouldn't be
messing with this now. Then again, I'm not sure anyone would have caught
these issues by looking at the demo download.

Sandy McDonnell

Previous by Author: HTML table of contents
Next by Author: Working with a team
Previous by Thread: Re: Guidelines on number of "things" per Help topic?
Next by Thread: Contract opening: Rapid-Writing Router Writer Resumes Requested

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

Sponsored Ads

Sponsored Ads