TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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-
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-
