RE: Examples of Minimalist Writing

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

Leonard, you've hit the nail on the head here.  Very nice explanation.
(Madelyn, this covers it pretty well.)

Here's a definition of Minimalism the artistic movement from Wikipedia,
that bastion of authority:

"Minimalism describes movements in various forms of art and design,
especially visual art and music, where the work is stripped down to its
most fundamental features. ... The term "minimalist" is often applied
colloquially to designate anything which is spare or stripped to its
essentials. ... Literary minimalism is characterized by an economy with
words and a focus on surface description."

Now here's the Wikipedia definition for "Minimalism (technical
communication)":

"Minimalism in structured writing or topic-based authoring is based on
the ideas of John Carroll. ... Carroll argued that training materials
should be constructed as short task-oriented chunks, not lengthy
monolithic user manuals that explain everything in a long narrative
fashion. ... Carroll observed that modern users are often already
familiar with much of what is described in the typical long manual. What
they need is the information to solve the particular task at hand. They
should be encouraged to do them with a minimum of systematic
instruction. ... Darwin Information Typing Architecture (DITA) is built
on Carroll's theories of Minimalism and [Robert E.] Horn's theories of
Information Mapping."

In John M. Carroll and Hans van der Meij's 1996 paper, "Ten
Misconceptions about Minimalism" (reproduced a couple of years later in
Carroll's follow-up book on this subject, "Minimalism Beyond the
Nurnberg Funnel"), the number one misconception is, "Minimalism means
brevity."

It was probably an unfortunate choice of words for Carroll to coin this
topic "Minimalism" (if in fact he was the one who did so), because of
the kind of confusion you get as shown above.

>From what I can tell in reading, the term actually began as "minimalist
instruction," and was a theory of instructional design, certainly not
writing.  It was meant to challenge the reigning instructional design
theory of the time, which I think was written about by Gagne and Briggs
in the 1980's.  It's the one we're familiar with for rote learning of
subjects.

(By the way, apologies for misspelling Dr. Gellevij's name in the prior
note.)

So the idea is, this brand of Minimalism (tech communication-related) is
about, for one thing, focusing on tasks (reading to do rather than
reading to learn), and for another, about presenting the minimum
information necessary for the user to get the job done -- allowing the
user's own mental model to fill in the gaps in information.

In the early 1980's, when PC's were first in use, it made sense to
describe every little widget in a user interface.  But today, everybody
knows what a check box is, and how to use it.  Same with a pulldown
menu.

The art of minimalist instruction, to me, is trying to figure out what
that bare essential information is, and what the user's mental model
contains, so you know what you can leave to the user to fill in.

The arts of prose and rhetoric do come into play, but it seems to me
that they are integrated with the environment you're dealing in.  So if
I'm writing a novel and elegantly describing a country landscape, that's
one thing.  But if I'm developing minimalist instruction and trying to
optimally and elegantly write about how to use a web application
interface, through online help let's say, then there's an art to how I
use words.

An example of the art of writing in this context comes from something I
was struggling with recently.

There's a feature that goes something like this:  "Click OK.  Your
changes are saved..." and I was trying to figure out how long they were
saved, because the developers told me the conditions under which the
original settings were restored.

So I was struggling with things like:

Click OK.  The next time you log out and log back in again, the original
settings are restored.

Click OK.  Your changes are saved until you log out and log back in
again.

Then I realized you could just say this:

Click OK.  Your changes are saved until you log out.

But a colleague came up with a better solution that I loved and ended up
using:

Click OK.  Your changes are saved until the end of the current session.

Nice!  That also allowed me to write, in a supplementary note, "The next
time you access the XYZ dialog box during the same session..."

It was just a much more elegant solution.  And I've seen a number of
examples of this in work done by my own department, so that's a source
for study.  But I'm trying to search out other examples done by other
people, to get a broader perspective.

To me, this is the art of minimalist writing within minimalist
instruction.  You must be elegant in your prose but within the
environment you're describing.  It's easy to be elegant when you're
describing a lush landscape because it's already lush so some of that
elegance is built in.  But elegance in *this* context means, what
satisfies the understanding of the user?  In the above example, I don't
have to describe the action of logging out.  And I certainly don't have
to talk about logging back in again.  The concept of a "session" is
enough -- it does the trick, and to me, it provides exactly the right
mental model.  (I should add that our users are fairly sophisticated --
a novice user might not understand the concept of "session" as easily.)

There is a fine discrimination in this kind of work but I think it's
worth cultivating.

One thing I meant to mention in the discussion on screen shots -- the
"less is more" idea particularly applies to online help, since the idea
is that you have the application open, and the exact screen visible (in
the configuration you're trying to apply), when you consult the help, so
you don't need to reproduce the screen that the user is looking at right
now UNLESS you really have to show something completely non-intuitive,
let's say.

Anyway... one could go on for reams on this, and I have to get back to
work. :)

I hope that helps at least show what I'm thinking about and why I
reached out to the group for more research and examples on the writing
aspect of Minimalist technical communication -- and why this is
different from pure plain language -- which is a beautiful area, don't
get me wrong.  I'm a big fan of it.  (I have an interesting story about
that I'll tell some other time, too.)

Thanks!

Steve 

-----Original Message-----
From: techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Leonard C. Porrello
Sent: Tuesday, September 29, 2009 8:36 AM
To: McLauchlan, Kevin; salt -dot- morton -at- gmail -dot- com;
techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Examples of Minimalist Writing

I would agree with Kevin, but what he's arguing against isn't
Minimalism, and the joke Chris made is a play on the idea of
"minimalism," not a reflection of Minimalistic technical writing. What
Kevin is arguing against is simply poor writing.

Minimalism is primarily concerned with creating knowledgeable,
self-directed users (as opposed to automatons who blindly execute
written procedures)--as efficiently as possible. For software, this
isn't done by documenting every procedure, workflow, or bit of
functionality. It's done by creating documentation that leads the user
through tasks that enable him to understand the application. This
invariably requires documentation that details common mistakes and error
recovery. Obviously, a purely Minimalistic approach doesn't work when
you must document "EVERY bobble and wingding." Nevertheless, Minimalism
can inform how you organize your documentation, and its insistence on
documenting common errors and error recovery is always applicable.

Minimalism is concerned with brevity and "plain language writing" only
to the same extent as is all good technical writing.

Leonard

-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of McLauchlan, Kevin
Sent: Tuesday, September 29, 2009 6:28 AM
To: salt -dot- morton -at- gmail -dot- com; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Examples of Minimalist Writing

 

> -----Original Message-----
> From: 
> techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr
-l.com [mailto:techwr-l-bounces+kevin.mclauchlan=safenet->
inc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Chris Morton
> Sent: Monday, September 28, 2009 4:06 PM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Examples of Minimalist Writing
> 
> >
> > Can anyone point me to some really good examples of
> minimalist writing?
> 
> 
> Yes.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


And THAT would be why I never trusted the concept of "minimalist"
writing in Customer documentation for anything more complicated than a
two-position switch.

How can you write "minimally" for someone who doesn't already know what
it is they must accomplish - i.e. relating their actual goal with the
function and capability of the product? If you just give them the bare
instruction to do a specific thing, that's fine... as long as they know
that that specific thing (among all the other possibilities available)
was what they need to do in that situation.

"To promulgate the framistan, do:

1) Two or three action words.

2) A couple more action words.

3) ... er... do we tell them that they are done, or does that exceed
minimalism? 

If we add a step that tells them where to go next, or what the options
are, and if we precede the list of steps with a little bit of
context-setting and explanation of _why_ they [might] need to perform
the particular task, or offer some decision criteria to select between
this task and a couple of other similar ones that satisfy
slightly/greatly different needs.... why, we've come back to the kind of
writing that I do.  Not minimalist. 

The only customer feedback I ever get is when: 

a) the info in my docs is incorrect (rare) 

b) the customers want more explanation on a given topic. 




 - Kevin
The information contained in this electronic mail transmission may be
privileged and confidential, and therefore, protected from disclosure.
If you have received this communication in error, please notify us
immediately by replying to this message and deleting it from your
computer without copying or disclosing it.


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

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
Leonard -dot- Porrello -at- soleratec -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/leonard.porrello%40so
leratec.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

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

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 Steve -dot- Janoff2 -at- teradata -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/steve.janoff2%40terad
ata.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

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

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