Too much structure

Subject: Too much structure
From: "Crockett, Walter" <Walter_Crockett -at- bmc -dot- com>
To: "'TECHWR-L'" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 14 Jun 2000 09:05:27 -0500

For some reason, the structuralist faction on this list is beginning
to remind me of my old sociology professors, who spent most of their time
trying to prove that sociology really was a science. I've also noted that
people are stooping to attack Andrew personally, while Andrew generally is
civilized enough to fire his bazooka into the air.
Before we pat ourselves on the back for creating foolproof
structures for foolproof documentation, let us remember that just about
every software help system, online or in print, lets you down just when you
need it the most. The main reason for this has little to do with whether
you've written a good outline and followed it, or whether you use the same
icon for every warning and the same introductory phrase for every procedure;
the main reason is that we're writing the darn stuff while it's being
invented. By the time we've really figured out what the user needs to know,
we're working on another project.
When I'm using an unfamiliar tool, or delving into the darker
regions of a familiar tool, the structure of the help -- the order of the
chapters, the internal logic of the template, etc. -- means nothing to me.
What I want to know is: Did they bother to index the term I'm looking for?
Can this tool do what I want it to do, and, if it can't, will they let me
know that, or will they join the Marketeers Club and write only about the
things it CAN do.
This is not to say that structures such as outlines and templates
and style guides don't make writing easier. They do make it easier, and they
make egregious errors of omission and confusion less likely.
But one must remember that writing is discovering. If you think you
already know everything you're going to write before you sit down and write
it, then you're not a writer, you're a secretary.
If we create a neat little box and write until we fill that neat
little box, we may end up with a neat little document whose only great
merits are its neatness and internal consistency. As we discover things
about the product, about the user, and about the help technology, we've got
to be flexible enough to work outside the box, and we've got to have the
freedom to change the structures and processes when necessary.
That said, I heartily endorse structures for programmers.

Walter Crockett

Previous by Author: Summary: Computer-based Training and Distance Ed (Long)
Next by Author: SI Units
Previous by Thread: "Index not Available" error message when opening indexed pdf docs
Next by Thread: RE: Too much structure

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

Sponsored Ads