Re: There's more to it than grammar

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

Debbie;

I can't agree with you on the "big picture" in more than half the cases that
come to mind.  My philosophy is that the manual/document should not teach
the user how to work in their profession (if this falls under the "big
picture" definition).  In my case, the documentation is for GIS
professionals.  Instead, it should explain how to use our software to do
what they need to do.

This may mean reaching elementary levels when it comes to explaining our
products while not talking down to them in their lines of work.  For
example, I explain how to program our software automation to create buffer
zones, but do not pretend to be able to educate them on where buffer zones
should and should not be used.  Sometimes I point out that, "the following
example may not make cartographic sense but is done to purposely distort the
map features so that the effects of running/programming the software are
noticeable".

Much online documentation does not connect the dots.  It's like having a kit
to build a car.  In this kit there are detailed explanations of each piece
but little or no explanation that the wheels connect to the axle, which
connects to the drive shaft, and so forth.

The product I am currently documenting contains no GUIs.  It is completely
done through ASP and DHTML programming with our objects and services.
Therefore, the user has no choice but read the documentation.  In my online
documentation, I have combined online reference help with online programming
guides (using HTMLHelp - which, by the way, they can run the map-generating
ASP examples "in place" in the help).  The reference help describes each
piece of the automation with which they program.  The programming guide
material describes the workflow, objectives, top-down example code, and
interaction between the elements.  This is the "big picture" as it applies
to the product.

The focus in the documentation is on using our objects to achieve results
and not on making a cartographically perfect map.  That is outside my
expertise and within my user's expertise.  For example, I show them how to
make a circular spatial filter around a city, set display ranges, and how to
symbolize the features.  They decide which elements, symbology, display
ranges are appropriate for the map and the spatial filter.

Mike Wing

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


> -----Original Message-----
> From: Debbie Warren [SMTP:dwarren -at- DTECHS -dot- COM]
> Sent: Friday, March 12, 1999 10:37 AM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject:      Re: There's more to it than grammar
>
> Don't you think that most users pick up a user's guide to locate how to do
> something or how to solve a problem? They usually have the big picture
> before they purchase the equipment or software. Providing lengthy text
> will
> only serve a few and scare away others looking for a quick answer. As you
> know, visuals are good for giving the user the big picture. That's why
> trainer use them to teach their students.
>
> The introduction should explain the general purpose of the manual and the
> product. You might expand and give more detail in a process manual. I've
> never created a process manual. Wouldn't a flowchart be a good choice to
> describe a process?
>
> Debbie W.
> dwarren -at- dtechs -dot- com
>
> From ??? -at- ??? Sun Jan 00 00:00:00 0000=
> =
>
>

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