Re: For references or directives, do you say where/why and then what/how, or vice versa?

Subject: Re: For references or directives, do you say where/why and then what/how, or vice versa?
From: Janice Manwiller <jmanwiller05 -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 17 Aug 2018 11:16:03 +0000 (UTC)

I also strongly believe in putting what the user is doing or looking for first, so they can verify that that's what they really want to do before taking an action.
I just think it's clearer and helps avoid unintended actions.
"Click OK ..... (user clicks OK) .... to completely erase your hard drive and launch the missiles."
An extreme and sort of silly example, but I still like having that chance to confirm.


Original message
I was reminded of this question during the earlier thread on whether to use
"see" or "reference" and decided a nice philosophical argument would be a
good way to round out the week. :)

My preference has always been to tell people why or where they're doing
something and then telling them what to do. This was a result from an
online training I took years ago that gave instructions such as:

"Type Foo in the Baz field."

on a really crowded screen, so you had no chance to FIND the Baz field
before the training had moved on through 5 more fields.

That experience is why I decided I'd be writing my instructions in the
following format, even if I had a screenshot with callouts:

"In the Baz field at the top right of the screen, type Foo."

Similarly, if I was referring people to someplace else for more
information, I'd word it as:

"For information on fiddling the thingbub on the Baz, see What's a Baz and
Why Do I Care?"

But I recently came out of 5 years in a job where the style was to give the
action first, as in:

"Type Foo in the Baz field."


"See What's a Baz and Why Do I Care? for information on fiddling the
thingbub on the Baz."

I've never liked that. I can understand that convention was used because
they wanted everything to be a direct instruction and to have the
instruction right up front, and normally I'd agree with them; but these are
two situations where I feel it's more important to tell the where or the
why before telling the how or the what.

Who has strong preferences for one versus the other, and why?

Lin Sims

Visit TechWhirl for the latest on content technology, content strategy and content development |


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-leave -at- lists -dot- techwr-l -dot- com

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

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: Re: Odd/Even formatting
Next by Author: Re: Odd/Even formatting
Previous by Thread: Re: Gmail [Reply] routing help
Next by Thread: 2019 release of Adobe Technical Communication Suite

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

Sponsored Ads