RE: Examples of Minimalist Writing

Subject: RE: Examples of Minimalist Writing
From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>, <salt -dot- morton -at- gmail -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 29 Sep 2009 08:35:55 -0700

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 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


Follow-Ups:

References:
Examples of Minimalist Writing: From: Janoff, Steve
Re: Examples of Minimalist Writing: From: Chris Morton
RE: Examples of Minimalist Writing: From: McLauchlan, Kevin

Previous by Author: RE: one vs 1
Next by Author: RE: one vs 1
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