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>]

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