TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Readers who don't read From:"Maureen J. Akins" <csvmja -at- ADMIN -dot- AC -dot- EDU> Date:Thu, 1 Apr 1993 20:05:20 EST
I like Karen Kay's answer. Examples should be offset whenever possible.
If not possible, bolding helps. My favorite way is to show the user
precisely what to type, without showing the prompt character(s), and then
follow it with an explanation of what is happening and what they can expect
to see on the screen.
So, it might look like this:
If you want to delete message number 2 and message number 5, type:
D 2,5
When you type the "D" the computer will fill in the rest of the letters
in the word DELETE. Then it will look for the message numbers you
don't want to keep.
My own stance on the concept of technical manuals is that manuals are for
reference. They should be well indexed, including synonyms for each
manual entry. Each section should be able to be understood on its own. A
user shouldn't have to read a manual cover to cover. Training manuals
should use clear and consistent examples and shouldn't simply parrot back
the screen. If users understood the screen, they wouldn't be looking in
the manual! Training manuals could recommend a user complete the lessons
in order, but shouldn't necessarily depend on it. That's why references
like "(This was covered in detail during lesson 2.)" is helpful.
Maureen
On Thu, 1 Apr 1993 17:03:43 CST, Karen Kay wrote:
>> > D(elete) 2,5 will delete messages 2 and 5.
>I had trouble understanding these examples, and the import
>of some of your "verbage" (sic). Perhaps it would be clearer
>if the examples were 1) offset somehow, independent from the
>explanation of what the command does, and 2) if the example only
>included allowable text.
>For example:
> D 2,5
>will delete messages 2 and 5.
>> don't read what I give them, but they follow all
>> examples like lemmings heading for the sea. I
>I thought that was what users are for?
>> considered just putting A or D in the manual, but I
>> don't think it is too good to surprise users with
>> unexpected sustem responses.
>But if they type A or D, they should get the EXPECTED
>response, shouldn't they?
>Karen Kay
---------------------------------------------------------------
| Maureen Akins Augusta College |
| Internet: makins -at- admin -dot- ac -dot- edu Computer Services |
| (706) 737-1484 GIST: 337-1484 2500 Walton Way |
| FAX: (706) 737-1773 Augusta, GA 30910 |
---------------------------------------------------------------
