Re: There's more to it than grammar

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

        <snip>

> One of the more problematic assumptions about technical communication is
> that it frequently assumes users already know, in general, what they want
> to do only only need assistance in error recovery, impasses, etc. Although
> there's nearly always an aspect of this involved in technology use, we
> often forget that users usually could also use a lot of help figuring out
> what The Big Picture actually is.
>
        <snip>


        ... Then there is the line between information relevant to your
application and information relevant to the user's field of specialty.
Maybe in a more general application, such as a word processor, some broad
information on how to use headers, tips on constructing resumes, and
presenting tabular data is useful and most likely appreciated.  But that is
because people using a word processor can range from a cub scout leader
writing a camping trip agenda to a CEO of a company adding to the quarterly
report.

        In other applications the user is a specialist in a field.  In my
case, the user is a GIS expert.  For years they drew maps by hand or through
mechanical drafting tools.  They know their material, but they do not know
how to use the software to do what they previously did by hand.  I do not
dare attempt to advise them on how to detail an escarpment or analyze
terrain.  An attempt on my part to try to "train/teach" them these things is
wrought with potential failure, insult to their intelligence, and
embarrassment.


> But why aren't we yet connecting this type of learning (which I think is
> closer to "training") to more general training, such as instruction on how
> to construct coherent sentences, how to write effective headings in
> reports, how to design and organize tabular data in ways that promote
> effective communication? (Or, many of you are saying at this point, "how
> to
> write a brief email message?") <snip>
>
>
        Isn't that what text books, courses, job training, and independent
study do?  Most software still requires the user to decide what is to be
designed, created, and so forth.  The software is typically a tool designed
to make the user's task for efficient, more productive, or less costly.  It
is not the onus of the software writer to teach the user the essentials of
the user's field.  It is to teach them how to apply the software to their
tasks.  There is great need on our part to learn what we can about their
tasks, but it is not a need to be able to perform those tasks better than
they can so that we may "educate" them.

        The "big picture", IMO, covers the workflows and connectivity of
tasks within my product but ends when it crosses into the user's area of
expertise.  In my case, I am not attempting to write an online guide to
cartography.  My documentation is not a text book.  Instead, I am writing
online guides to producing computer-generated maps.  I cover how, why, and
what order to perform operations and cover dependencies/effects between
software modules/elements as done through the software interfaces.  The
focus and scope is on my product.  I am telling them how to use the tools,
not how to build a bridge, a house, or a map.


> What concerns me more is that online help authors seem afraid to even
> allude to such issues; by ignoring them, we tend to make them disappear.
> So when MS Word, to continue my example, walks users through a Wizard that
> designs their resume but doesn't talk about the *reasons* one might choose
> one of three very different layouts, users are encouraged to think that
> the choice of layout doesn't even matter.<snip>
>
>
        If the writer leaves the user with a scattering of non-connected
parts that are PART OF THE APPLICATION for which they document, then they
task is incomplete.  However, if the writer has documented the workflows (if
applicable), provided sample code/usage, provided details on the software,
and so forth, they have met their burden.   The writer is not responsible
for the user's level of expertise in their own field.  Alluding to the user
that we know more about their field (which is rarely the case) than they do
is wrong (It's analogous to when our American Democratic party says that the
government knows more about tending to individual affairs than does the
individual;^).

        In the example of the resume wizard, I feel that it is appropriate
for the writer to explain the results of the options (and combinations,
thereof) that the wizard presents.  It is inappropriate for the writer to
tell the user what is or is not a great resume for that user.


> - Johndan Johnson-Eilola
>
        Mike Wing

Michael Wing (mailto:mjwing -at- ingr -dot- com)
Staff Writer/ Web Applications Developer
Intergraph Corporation; Huntsville, Alabama
http://maps.intergraph.com

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=