[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

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: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 16 Aug 2018 15:04:21 -0400

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 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: Structural Rules [Was: Odd/Even formatting]
Next by Author: Re: Training design
Previous by Thread: 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?

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads