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: Andrea Shanahan <amshanahan -at- gmail -dot- com>
To: Lin Sims <ljsims -dot- ml -at- gmail -dot- com>
Date: Thu, 16 Aug 2018 20:52:21 -0400

100% with you on this! It's something recently discussed on my team. I keep
looking for evidence supporting this view.

Fwiw, I found this in the online MS style guide, which appears to support
what I call "context first" :

https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions

By "context" I mean orientation, whether it's location on a menu or in a
field, for example, while tending to avoid giving "traffic directions" like
"far left top corner") or the purpose or intent of the actionâi.e., that
which is to be accomplished.

Unless a step is either very short and/or obvious ("Click Save"), or unless
it's redundant or pedantic to do so, "context first" almost always works.

On Aug 16, 2018 2:26 PM, "Lin Sims" <ljsims -dot- ml -at- gmail -dot- com> wrote:

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 amshanahan -at- gmail -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:

References:
For references or directives, do you say where/why and then what/how, or vice versa?: From: Lin Sims

Previous by Author: RE: Use of word "reference" when cross referencing
Next by Author: RE: Turn OFF smart text selection in PDF
Previous by Thread: Re: For references or directives, do you say where/why and then what/how, or vice versa?
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