Re: Use of Optional in instructions

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

I don't understand what you're trying to say.

To put what I said another way, I've never seen a topic (whether
generated with DITA or otherwise) that started with step 1 of an
ordered list of instructions.

There's always at least a title, which may be sufficient to identify
the task to be performed. For example, "Create a New Project File" or
"Delete a File" might not need any further description.

On Tue, Sep 15, 2009 at 7:13 PM, Pro TechWriter
<pro -dot- techwriter -at- gmail -dot- com> wrote:
> We use DITA, which means the user does not necessarily read a concept before
> performing a task. And, there is not usually a description of what will be
> accomplished. I do know that seems weird, but that is the DITA way for the
> most part.
> And the way I wrote the example in the original (to which some people said
> "ewwww") is prescribed by our doc standards :-)
> Changing with the times--and methodologies,
> PT
>
> On Tue, Sep 15, 2009 at 2:03 PM, Robert Lauriston <robert -at- lauriston -dot- com>
> wrote:
>>
>> 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