TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> I don't know how others feel about tutorial or quick start material,
> but I dislike tutorial information which takes the form:
> Preview: Here's what we're going to do in this section.
> Procedure: Here's how to do it.
> Review: Here's what we just told you.
> Practice: And here's a few things you can try that we didn't describe.
> I don't know where this tutorial form came from, but when I want to get
> up to speed on a product or procedure I find going through this style of
> tutorial is like wading upstream through a river of molasses, and I skip
> all the preview, review and practice steps!
I think this must be related to the "Tell them what you're going to tell
them, then tell them, then tell them what you've told them" mantra that
I hear repeated every so often as if it is indisputable truth. That's
a recipe for excess verbiage no matter where you use it, and it implies
some fallacies that infect a lot of technical writing.
Despite the fact that any strategy is undoubtedly applicable to SOME
project somewhere, this idea seems most useful if you know your reader
will be trapped in a snowstorm with absolutely nothing else to read.
Hey -- users have plenty of other stuff to do, and they'll drop our
carefully crafted prose as soon as they can figure out how to get their
primary job (which is not reading documentation) done!
People don't read from the first page of a doc towards the last; they
usually get in and get out as soon as they can. This means they don't
like stuffy writing (writers have told me that this makes readers "work
a little harder" to find what they need), they resent discursiveness
and in-jokes, and they depend on a reliably consistent style to keep
them from getting lost.
Anyway, if Minimalist Writing means cutting out the crap and being
immediately useful, I'm all for it. Since indexes don't get in
anyone's way, I wouldn't cut them out myself. And there was another
posting that said something about making users experiment a bit to find
out what they needed to know ...?? Maybe I misunderstood that.
Arthur Comings
Senior Technical Writer
GeoQuest Data Management Division
5725 Paradise Drive, Suite 100
Corte Madera, CA 94925
(415) 927-6215
atc -at- corte-madera -dot- sds -dot- slb -dot- com
