The big picture (more than grammar)

[Philomena Hoopes <PHILA -at- MAIL -dot- VIPS -dot- COM>]

I second that view, long or not, Ken!

                <snip> Not once in all that time, was I ever able to
convince anyone in the tech writing group that we should be including
illustrations to show concept, overview, basic actions, etc. in order to
help the user get the "big picture." (Despite the fact that such aids were
routinely drawn on fancy copy-making marker boards when customers came to
headquarters for training.)

This raises an interesting question, one that our product trainer and I have
been discussing for a long time: where do documentation and training
overlap? Until recently, the training classes were geared toward giving the
big picture, supplemented by the documentation, which primarily gave the
nitty-gritty feature descriptions and procedures. As our customers multiply,
and our product evolves, however, this just isn't sufficient. What should be
the relationship between Training and Documentation?

                <snip> I find that I need a good overview when I'm learning
something new; an
                overview that approximates an experienced person introducing
me to
                what's going on, what's important, how things work.

As a corollary, where do on-line tutorials fit into this picture? This is
the area that I find frustrating in most software packages -- the online
training is full of procedures rather than concepts. Like you, Ken (and IMJ
like most people), I need the big picture first. Once I know the basic logic
behind the product, I have a groundwork for understanding the procedures.

                <snip> Personally, I would rather see software manuals
contain concrete
                examples of how to do things than to explain how to do many
discrete
                operations step by step. Because, doesn't it always seem
that the manual
                falls short in helping you do what YOU want to do? In the
CNC hardware
                business, engineers and tech writers spend a lot of time on
what are
                called "Application Notes." How the product is actually
applied by the
                user in the field. Maybe there should be more of that in
manuals for the
                non-specialiast software.

Hear, hear...The key, to me, is to present the way the product thinks -- and
how the user needs to think in order to use the product effectively.

The sticky question is this: most software products are designed for maximum
versatility, and progressive releases are likely to become increasingly
complex.  A minimalist, building block approach of documenting only features
and procedures allows the user to create pretty much anything with those
blocks, including tangled messes (and in our product, multi-megabyte
queries). How much thinking should a complex product do for the user,
through wizards and such, and how easy should it be for the user to go
behind the scenes to perform complex functions manually? This doesn't even
begin to touch the question of an internal development application for
customizing special functions.

It's a delicate balance, fer sure...and given the normal time allowed
between releases, a certain amount of triage is required. I think this is
the bottom-line reason for most documentation being structured on the
"building-block" model.

Philomena Hoopes
Phila -at- vips -dot- com <mailto:Phila -at- vips -dot- com>
VIPS Healthcare Information Solutions, Inc.
(410) 832-8330 ext 845

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