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

[Lin Sims <ljsims -dot- ml -at- gmail -dot- com>]

My only qualm with this, handy as it can be, is that some steps may not be
associated with an item on the UI. If you use one graphic as a reference,
you potentially have a graphic with "missing" numbers, which I think would
be confusing. The alternative would be to use a graphic for almost every
step, which bloats the manual and requires a lot more work with graphics.

My current preference (subject to change with better data) is to use
letters as callouts on the graphic and refer the reader to that callout
letter. This was after much grumbling on my part, since my preference is to
use numbers, not letters, but the argument that the reader could interpret
the callout number as being associated with a numbered step was enough to
convince me to change my ways.

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

> 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 ljsims -dot- ml -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
>



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