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:Looking for Opinions/Criticism From:Larry Weber <larry_weber -at- HOTMAIL -dot- COM> Date:Tue, 26 Aug 1997 02:20:35 PDT
Hello,
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:
FIND STRING
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
box.
4. Specify in which direction to move the search in the Direction group
box.
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:
FIND STRING
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
operation.
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,
LW
______________________________________________________
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
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
