RE: Use of Optional in instructions

Subject: RE: Use of Optional in instructions
From: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: "Boudreaux, Madelyn \(GE Healthcare, consultant\)" <MadelynBoudreaux -at- ge -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 11 Sep 2009 15:30:42 -0600

Boudreaux, Madelyn wrote:

> Richard Combs wrote:
> >RIGHT: "To accomplish X, do A."
> >WRONG: "Do A to accomplish X."
> Interesting. I've always preferred the other route, on the grounds
> Richard's method buries the lede. The procedure is what you do, and
> explanation, editorializing, or notation is secondary. A user who is
> just following orders reads the DO THIS step, and skims the
> that follows; a more curious user reads it all. Users are like ornery
> horses: you can lead them to understanding, but you can't make them
> partake.

"Buries the lede"? But we're not writing news reports, inverted-pyramid
style. We're telling people how to perform a task. As others have noted,
the user who reads "Do A" and immediately does it may not be happy upon
discovering that she just "accomplish[ed] X" when she really intended to
accomplish Y.

IMHO, the critical information -- the "lede," if you want to call it
that -- amounts to this: "Dear reader, you now have a decision to make.
Do you want to accomplish X? If so, ..."

Sorry, but I thought this was TW101 since at least the 80s. If an
instruction has a qualifier, state the qualifier first so the reader can
determine whether the instruction applies.


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
rgcombs AT gmailDOTcom


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.

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!

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

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 for more resources and info.

Please move off-topic discussions to the Chat list, at:


RE: Use of Optional in instructions: From: Combs, Richard
RE: Use of Optional in instructions: From: Boudreaux, Madelyn (GE Healthcare, consultant)

Previous by Author: RE: Use of Optional in instructions
Next by Author: RE: Use of Optional in instructions
Previous by Thread: Re: Use of Optional in instructions
Next by Thread: RE: Use of Optional in instructions

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

Sponsored Ads