Re: Use of Optional in instructions

[Robert Lauriston <robert -at- lauriston -dot- com>]

I'm not sure I've ever seen a help topic that didn't start with a
description of what the steps that follow will accomplish.

If the topic's written well, it shouldn't matter whether you get there
by invoking a context link, choosing an entry in the TOC, index, or
search results, or following a cross-reference from another topic.

On Tue, Sep 15, 2009 at 11:53 AM, McLauchlan, Kevin
<Kevin -dot- McLauchlan -at- safenet-inc -dot- com> wrote:
> I think the above argument holds water for books, but not so much for Help, where the reader might arrive from anywhere (including an index entry, a keyword search, or random karma) and not have followed a path that would le[a]d[e] them to anticipate a particular "accomplishment" other than the one they already had in their head(s).
>
>  Lauren opined:
>
>>
>> Boudreaux, Madelyn (GE Healthcare, consultant) wrote:
>> > Richard Combs wrote:
>> >> RIGHT: "To accomplish X, do A."
>> >>
>> Ewww...
>> >> WRONG: "Do A to accomplish X."
>> >>
>> I would not write an instruction like this either, but it gets rid of
>> the non-committal sound of the "right" option.  The instruction for
>> accomplishing X should already be in a section for
>> accomplishing X, so
>> there should not be a need to soften the fact that an action will
>> accomplish X.  So in the section for accomplishing X the instruction
>> should be, "Do A."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help  
2009 tips, tricks, and best practices.
http://www.doctohelp.com/SuperPages/Webcasts/

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat