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

[Keith Hood <bus -dot- write -at- gmail -dot- com>]

Considering the scientists I've known, he's even more likely to need being
taken by the hand and walked through in short, easy steps than the lab
assistant. He'll be so busy looking at the forest he won't see the bear
trap between the trees.

On Thu, Aug 16, 2018 at 10:29 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:

> 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