RE: Examples of Minimalist Writing

["Janoff, Steve" <Steve -dot- Janoff2 -at- Teradata -dot- com>]

Thanks, Madelyn -- that's an interesting site.  Good for plain language
studies.
 
I regret, though, that Fred is on target here.
 
While there's overlap between minimalism and plain language, they're
really two very different subjects.
 
Maybe I should be more clear in stating that I'm seeking examples of GUI
documentation.
 
Also, I'm writing in a DITA environment, so everything is broken into
task topics, concept topics, and reference topics.
 
One of the rules is not to mix content that belongs in one type of topic
into one of the other types.  So no task-type instructions in a concept
topic.  But that's a separate issue.
 
Maybe an example is in order, although I apologize in advance if this is
not a good one.
 
Here's a non-minimalist version of saying something -- I'll use square
brackets to indicate formatting:
 
    Click the dropdown arrow next to the [b]Filename[/b] field and
select a filename from the list that appears.  [maybe even an icon image
of the arrow somewhere in there, or a full or partial screenshot showing
the action being performed]
 
This might be a minimalist way to say the same thing:
 
    Select a [b]Filename[/b] from the list.
 
Or even:
 
    Select a [b]Filename[/b].
 
(No screenshot and no icon in the above two examples -- but it's the
text that's more important.)
 
A too-vague version would be to give you the instruction but not tell
you how to get to the dialog box that contains this dropdown list.
 
But one of the ideas is that you no longer have to tell a reasonably
sophisticated user how to use a GUI control, such as a dropdown menu.
So you eliminate describing the interface.
 
This is an old topic, but I find that the art of minimalist writing or
minimalist instruction, if there is an art, is to find that borderline
between what's too vague and what's too explicit.
 
The extremes are:  I can write 50 pages of excruciatingly detailed
instructions describing every tiny nuance of the interface that the user
must interact with, or at the other end I can just say, "Just do it" and
let them figure it out for themselves.
 
Surprisingly, with greater user sophistication, the answer seems to be
more toward the end of "Just do it."  Look at some of the aftermarket
software user's manuals of the 1990's, and you see doorstop-sized tomes
with every screenshot under the sun and every instruction there is, not
to miss a thing.
 
You might be able to accomplish the same thing today in about 25-50
pages (down from 700 or whatever), letting the user's mental model fill
in the gaps.
 
But the art of minimalist writing is in taking an information-rich
sentence, phrase, paragraph, or topic, and paring it down to its bare
necessities.  Not exactly going from haute couture on the runway to a
loincloth, but in a way it's not far from that.
 
Also, screenshots are of questionable necessity, but the research seems
to be all over the map on that one -- although mostly leaning toward not
needing them, or only needing a select few.
 
Anyway... it's the writing I'm trying to find examples of.  I was able
to locate the "Minimal Manual" from the 1980's, or whatever it was, for
the IBM Displaywriter, I believe, but that's not exactly up to date.  In
those days, people really did need hand-holding.
 
I'm looking for examples that are relevant for today's UI documentation.
 
Thanks if anybody has any thoughts, or if not, then it's just a case of
cultivating the art, skill, or whatever, on one's own.
 
Steve
 
PS - I'm thinking maybe I should hang out on the DITA lists or something
-- that might be a place where people talk about this kind of stuff more
often, and have come up with some solutions.  I welcome anyone's advice
here on fruitful outlets for that too.  Thanks.
 


________________________________

From: Fred Ridder [mailto:docudoc -at- hotmail -dot- com] 
Sent: Monday, September 28, 2009 2:14 PM
To: madelynboudreaux -at- ge -dot- com; Janoff, Steve; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Examples of Minimalist Writing


While the examples on this website are interesting case studies of how
atrocious governmental writing can be, I don't think there is a single
"after" example that comes very close to minimalist writing as most of
us understand that term.

-Fred Ridder

 
> Subject: RE: Examples of Minimalist Writing
> Date: Mon, 28 Sep 2009 16:58:44 -0400
> From: MadelynBoudreaux -at- ge -dot- com
> To: Steve -dot- Janoff2 -at- Teradata -dot- com; techwr-l -at- lists -dot- techwr-l -dot- com
> 
> Steve Janoff wrote:
> >I'd really like to see examples of how other 
> >writers have achieved a minimalist style.
> 
> Hi, Steve:
> 
> Plainlanguage.gov is a treasure trove. Here's their before-and-after
> page:
> http://www.plainlanguage.gov/examples/before_after/index.cfm 
> 
> Sincerely,
> Madelyn Boudreaux

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help  
2009 tips, tricks, and best practices.
http://www.doctohelp.com/SuperPages/Webcasts/

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat