Re: Minimalist Writing

Subject: Re: Minimalist Writing
From: Arthur Comings <atc -at- CORTE-MADERA -dot- GEOQUEST -dot- SLB -dot- COM>
Date: Fri, 5 Nov 1993 12:55:21 PST

Dave Venzke writes:

> 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

Previous by Author: Re: English for Asian readers
Next by Author: Re: "Overpriced" software
Previous by Thread: Re: Minimalist Writing
Next by Thread: thanks: tech wrtr/eng. resends, now more

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

Sponsored Ads