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

Subject: For references or directives, do you say where/why and then what/how, or vice versa?
From: Lin Sims <ljsims -dot- ml -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 16 Aug 2018 14:26:44 -0400

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."

or

"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 | http://techwhirl.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-leave -at- lists -dot- techwr-l -dot- com


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

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

Previous by Author: Re: [BULK] Re: Use of word "reference" when cross referencing
Next by Author: Re: For references or directives, do you say where/why and then what/how, or vice versa?
Previous by Thread: Re: Microsoft Manual of Style vs. github.com/MicrosoftDocs/microsoft-style-guide
Next by Thread: Re: For references or directives, do you say where/why and then what/how, or vice versa?


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

Sponsored Ads


Sponsored Ads