Re: Looking for Opinions/Criticism

Subject: Re: Looking for Opinions/Criticism
From: Jim Purcell <jimpur -at- MICROSOFT -dot- COM>
Date: Tue, 26 Aug 1997 09:52:19 -0700

Larry Weber writes:

<Problem snipped>

Here's what Larry inherited:

> 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).
>
This is definitely overkill. Making the procedure so long makes this
look difficult, when in fact it isn't. Given that the dialog box is
wired for context-sensitive help, you can stick to the basic procedure
and let the options take care of themselves. Losing the duplicate topics
is an easy decision.

<snip> 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
>
This, on the other hand, goes too far the other way. To find a search
string (this is the topic, is it not?), you have to open the dialog box,
but you also have to do some other things. You can defer the optional
stuff to the context-sensitive help, but you can't skip the main task.

> 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 have to disagree here. Don't confuse being specific with being
long-winded. You can be quite specific on small subjects without
spending many words. And a procedure always needs to look like a
procedure. Procedures run into a main paragraph look like explanation,
and people tend not to read explanations if they can avoid it. Hiding
your procedure in a paragraph makes it less likely to ever be read at
all, and if nobody is going to read it, why are you writing it in the
first place?

What the user does once she gets the dialog open may seem obvious--it
probably is obvious--but you still need to say it. If you propose to
tell people how to search for a string, you have to tell them. In a
tutorial, you could do the minimal guided exploration thing, but not
here.

In general, I wouldn't explain every means of getting to the dialog box.
I'd choose one (I would use the menu, but any single method will do) and
make sure that the alternate means are explained elsewhere, maybe in a
general discussion of toolbars or context menus. Right here in this
procedure, you need something that is short and works.

> 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?
>
In both cases, this topic seems to vacillate between being
product-oriented description of a dialog box and a task-oriented
explanation of a procedure. You need both, but apparently you already
have the product-oriented descrption online. I would make this topic
explicitly task-oriented, so I wouldn't title it "Find String" and spend
the introductory paragraph explaining what the dialog box is for. The
dialog box is really incidental to the task, and the task should be the
focus. Here is what I would write:

Searching for a Text String

You can search for a character string in the current buffer, in multiple
buffers, or in multiple files.

To find a string:

1. From the Search menu, click Find String.

2. In the Search field of the Find String dialog box, enter the search
string.

3. Set the scope of the search and any other options you need. For
additional search options, click the Options button.

4. To initiate the search, click OK.

For help on search options, click an option in the Find String or
Options dialog box and press F1.

Hope this helps,

Jim Purcell
mailto:jimpur -at- microsoft -dot- com
My opinions, not Microsoft's

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


Previous by Author: Re: hyperlink style question
Next by Author: Re: Receiving Word 6 files
Previous by Thread: Re: Looking for Opinions/Criticism
Next by Thread: SENIOR TECHNICAL WRITER - SF Bay Area


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


Sponsored Ads