Looking for Opinions/Criticism

Subject: Looking for Opinions/Criticism
From: Larry Weber <larry_weber -at- HOTMAIL -dot- COM>
Date: Tue, 26 Aug 1997 02:20:35 PDT


First--apologies for this long post.

I've recently started working on a small product in a large software
corporation and I'm a bit concerned about the usefulness of the Winhelp
files we provide. It seems to me that the previous writers were more
concerned about "current trends" such as numbered procedures than the
actual usefulness of the information. For instance, here's the
information we provide for a somewhat standard Search dialog:

The Find string options is used to find a string of characters in the
current buffer, across multiple buffers or across multiple files on
disk. For quick, context-sensitive search use the shortcut menu.

To find a string:
1. Select Find string from the Search menu.
2. Enter the search sting in the Search value field.
3. Indicate where to search for the specified string in the Scope group
4. Specify in which direction to move the search in the Direction group
5. Select the Match case check box if you want to perform a
case-sensitive search.
6. Select or clear the Regular expr. check box.
7. Select the Options button for additional search functionality.
8. Choose from the following options to begin the search: Find, First,
Last, Find all.

Each mention of a control in the above procedure is a link to an
explanatory topic in a secondary window. However, because we provide
Context Sensitive Help, all dialog control information is duplicated in
a regular topic AND a CSH topic (a real maintenance headache).

I don't find the above procedure especially helpful, and I don't think
the FIND STRING dialog is hard to use. The audience is programmers. I
believe we can get away with being somewhat general in the Help for the
dialog, letting users access the CSH for specifics. Therefore, I'm
considering deleting the redundant dialog control topics, and I've
written the following for the main help topic:

Use the Find String dialog box to find a string of characters in the
current buffer, in multiple buffers, or in multiple files on disk. Use
the Options button to display additional controls for the search

To access this dialog box, do one of the following:
· click {bmp of button} on the toolbar
· from the Search menu click Find String
· from the shortcut menu click Find String

My theory is to be general in the main topic, only mentioning specific
controls when intuitiveness is not apparent. I will also provide
numbered procedures when my judgement says that they are necessary.

I'm looking for opinions. Do such changes, from a user's standpoint and
from the standpoint of a writer who must maintain the information, make
the help better? Would you do anything different?

Thanks in advance,


Get Your Private, Free Email at http://www.hotmail.com

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html

Previous by Author: Re: What do you call them?
Next by Author: Re: Is there a nice way to say...
Previous by Thread: RoboHELP problem
Next by Thread: Re: Looking for Opinions/Criticism

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

Sponsored Ads