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

Your preference would be my choice for a text-only instruction. In the
few instances when I have written for software, my preference was to
use the shorter instruction and key each numbered step to a matching
callout on a figure.

Gene Kim-Eng

On Thu, Aug 16, 2018 at 12:04 PM, Peter Neilson <neilson -at- windstream -dot- net> wrote:
> I agree with your preference.
>
> It's generally a blunder to explain obscure things by referring to the
> totally unknown. The good teacher attempts to find out what his students
> already know. Mathematicians in particular fall into the sin of explaining
> the particular case as an instance of the general case. For example, in
> attempting to explain vectors, they might say that a scalar is a zero rank
> tensor, and a vector is a first rank tensor. Rather little help, eh?
>
> Videos explaining computer subjects sometimes make a similar blunder: "You
> can see if we click here, then the expression over there becomes ..." The
> person speaking knows where "here" and "there" are, but we cannot read his
> mind to follow his cursor.
>
>
>
> On Thu, 16 Aug 2018 14:26:44 -0400, 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?
>>
>>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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