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

[Gene Kim-Eng <techwr -at- genek -dot- com>]

As with most things, this is a know-your-reader situation. Is your end
user a scientist trying to create a never-been-done experiment? Or is
it a junior lab assistant whose job is to load some samples, fire up a
routine SOP test sequence and then go wash the beakers and feed the
rats?

Gene Kim-Eng

On Thu, Aug 16, 2018 at 6:29 PM, Keith Hood <bus -dot- write -at- gmail -dot- com> wrote:
> I say always give the orientation first. If there is a lot of verbiage
> needed to describe the location of the input feature, and you give that
> after you give the input that should be used, some people by the time they
> find the right location, they will have forgotten what they're supposed to
> input.
>
>
>
> On Thu, Aug 16, 2018 at 7:52 PM, Andrea Shanahan <amshanahan -at- gmail -dot- com>
> wrote:
>
>> 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 bus -dot- write -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 techwr -at- genek -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