Re: Format for instructions

Subject: Re: Format for instructions
From: Judith Grobe Sachs <judygs -at- UIC -dot- EDU>
Date: Thu, 14 Jul 1994 08:39:16 CDT

Sally Marquigny said (with reference to the "A need B with C" thread)

> When I write documentation, I try to empathize with the user, of
> course. Like a broken record, I repeat after nearly every crumb of
> information, "Why do I need to know this?" Answering this question
> *in the text* not only assures that I've covered the topics fully,
> but also frequently helps me to see the best format for that
> particular factoid (or the whole concept, or whatever).

I am certainly playing the Devil's advocate here, because I too
like to know the why's and how's when I'm reading documentation.
And I'm likewise inclined to include them when I write it. Since I
write for a captive and vocal audience (a university), I get a lot
of feedback. And much of it is "I don't want all those details -
just tell me how to do it!" (From college faculty no less; this
lack of intellectual curiousity never fails to amaze me.) Of
course, I also hear just as vocally when I do leave something
out, or when what they need is on the 4th page of a 10 page
document and they didn't have the patience to find it. Oh, well!

So, the moral of this story is one we've all heard before. Know
your audience, and make sure they know what you're trying to do in
each particular piece of documentation. If you're writing a
"Getting Started With ..." type of thing, don't confuse things by
including explanations. But you might want to tell them that
up front, and tell them were they can find the explanations
if they are so inclined.

As always, my 2 cents. Judy

Judith Grobe Sachs Telephone - (312)996-3758
Computer Center, University of Illinois at Chicago FAX - (312)996-6834
Bitnet: U11371 -at- UICVM Internet: judygs -at- uic -dot- edu

Previous by Author: Re: Headers, Footers, & Page Nbrs.
Next by Author: Gophering on the Web
Previous by Thread: Format for instructions
Next by Thread: Format for instructions

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

Sponsored Ads