RE: Examples of Minimalist Writing

Subject: RE: Examples of Minimalist Writing
From: "Janoff, Steve" <Steve -dot- Janoff2 -at- Teradata -dot- com>
To: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>, "Mike Starr" <mike -at- writestarr -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 1 Oct 2009 14:41:27 -0400

This is excellent, Leonard. I haven't read all the way through
Carroll's books but I've read enough about the subject to know that
you're spot-on.

In topic-based authoring you would probably break this into at most 3
topics: a task topic, a reference topic, and (if necessary) a concept
topic.

Task topic: "Decreasing the Color Depth" or "Decreasing the Color Depth
of an Image" or something like that (as Milan suggests). Step by step,
and at most you would run through the different fields: Preview, Zoom,
Pan, Settings, Palette, Reduction Methods, Options, etc. (couple of
others in this dialog box).

Reference topic: "Color Depth Settings," or something like that, with a
table listing the meaning of each field in this dialog box and the type
and range of values.

Concept topic (if necessary): Something like "About Color Depth" or
"About Image Reduction" or "About Images" or whatever. Even "About the
256 Color Palette." Here you would be restricted to concept-based
information on this aspect of the interface.

If you're using DITA (which is topic-based authoring), then my
understanding is that this is the way you do it.

Minimalism isn't about "leaving out information" or "letting the user
figure it (everything) out for themselves." In your example, you
wouldn't write an instruction like, "Select one of the radio buttons in
the Palette field." That's describing the interface. You would say,
"Select a [b]Palette[/b] setting" and you'd describe the options in the
reference topic. It's separating tasks from reference material from
concept material. If you put it all in one help file, it's three times
as large and the user has to sort out task vs. reference vs. concept
information for themselves. Carroll and colleagues found (if I have
that right) that it's more effective to separate this information. And
some of it, you could leave out entirely.

Mike, the kind of frustration you express in your article is addressed
in the paper "Ten misconceptions about minimalism" by Carroll and van
der Meij from 1996 in IEEE Transactions on Professional Communication,
reproduced in Carroll's second book on this topic, "Minimalism Beyond
the Nurnberg Funnel." If you can get that paper or the book, it would
be a fruitful read for you.

Looking forward to more good discussion on this.

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: Thursday, October 01, 2009 9:33 AM
To: Mike Starr; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Examples of Minimalist Writing

Similar to Kevin, Mike isn't arguing against Minimalism--as it is
defined by Carroll. A Minimalist approach doesn't preclude reference
documentation. It precludes giving step-by-step directions covering how
to do things that users already know how to do or can easily figure out.
In the example Mike provides (How to increase color depth....), #1 is
important as it tells the user where to find the wanted functionality.
However, a table detailing all of the options could follow #1. And if
the original image would be irreversibly changed by the process, this
information would also be included. On the other hand, if the original
is not irreversibly changed, Minimalist instructions would include
information on how to undo changes that may have been made by mistake.
If you would omit anything, it would probably be #2. What user that
understands color depth and the "256 Color Palette" would need to be
told to click "OK"?

Having said all that, I have to add that I haven't read Carroll's book
ten years and might have forgotten something or transmogrified his
theory into my own pet creation. If anyone who has actually read
Carroll's work cares to show me the errors in my understanding of
Minimalism, I'd be grateful.

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 Mike Starr
Sent: Thursday, October 01, 2009 4:33 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Examples of Minimalist Writing

I started responding to the list with an email but it turned into an
article...

http://www.writestarr.com/minimalism.htm

Mike
--
Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Technical Illustrator
Graphic Designer - Desktop Publisher - MS Office Expert
(262) 694-1028 - mike -at- writestarr -dot- com - http://www.writestarr.com

Leonard C. Porrello wrote:
> 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


References:
Re: Examples of Minimalist Writing: From: Mike Starr
RE: Examples of Minimalist Writing: From: Leonard C. Porrello

Previous by Author: Re: Doc Design and Conventions
Next by Author: RE: Examples of Minimalist Writing
Previous by Thread: RE: Examples of Minimalist Writing
Next by Thread: Re: Examples of Minimalist Writing


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


Sponsored Ads