Re: Minimalist docs

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

Geoff Hart writes:

> Consider the sign "fresh fish for sale daily". Obviously,
> the fish can't be fresh if you don't sell them daily... so
> let's drop that bit. Now you wouldn't be advertising the
> fish if they weren't for sale, and nobody would try to sell
> stale, old fish... so let's drop "fresh" and "for sale"
> too. That pretty much leaves us with one word: "fish". But
> we're not done yet... surely anyone who walks past the
> store will know (whether by sight or smell) that you're
> selling fish. So let's drop that word too.

> You can't get much more minimalist than that... no words at
> all. Hmmm... did someone say "parable"?

This is false minimalism.  You've wielded the knife before learning
the nature of the patient's injuries.

The first three questions one should ask in any documentation project
are:

1. Can the client pay for my services?
2. What is management trying to accomplish?
3. What is the reader trying to learn?

Once we've received a satisfactory answer for question 1, we deal with
question 2.  The point of a "Fresh fish for sale daily" sign is to
remove consumer doubts.  The "fish for sale" part reassures the consumer
that you sell directly to the public.  "For sale daily" indicates that
you are open for business today and every other day.  "Fresh fish"
asserts that your fish are fresh -- a point that might otherwise
cause hesitation, since stale fish are worse than useless, and many
people can't tell the difference when shopping.

Note that we've dealt with three independent consumer concerns in five
words, and dealt with questions #2 and #3 at the same time.

Having no sign at all leaves all the questions open.  Are these fish
for sale to the public?  Are they fresh?  Can I rely on this place
as a source of fish, or is the supply of fish intermittant?  And
also: Do these guys really want my business, or do I have to stand
around and catch the eye of some hostile clerk before finding out whether
their stinking fish are for sale to the public at all?

        -- Robert
--
Robert Plamondon, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html