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'll cheat and redefine the question: To me, minimalism
> means giving readers everything they need to know, and
> nothing more that interferes with this information.
>
To me, this is not a definition of minimalism; it's a definition of good
technical writing.
<snip>
> If pressed, I'd say that people who want
> to learn _about_ something need more than a minimalist
> approach, whereas those who simply want to _do_ something
> and forget about the details will appreciate minimalist
> docs.
>
This seems to be the reverse of minimalism as expounded by Carroll,
Rosson, et al. Carrol and Rosson present minimal documentation as an
alternative to the more typical interactive training in which the user
reads a lot and does some canned exercises that may or may not be
relevant to the trainee's real needs. Carroll's alternative would be
more like this:
Lesson one, entering text: "A word processor is kind of like a
typewriter. Take a business letter or document you are working on right
now and type it into the document window." Lesson two, formatting text:
"Actually, a word processor does more than a typewriter. For instance,
you can change the format of selected text. Drag the mouse over some
text to select it. Choose various options on the Format menu and see
what happens."
The idea is that by using examples that are real to the trainee and by
encouraging guided exploration of the product, tasks and concepts become
more firmly fixed in the user's mind. These are training goals, not
documentation goals.
Unfortunately, Carroll's idea has been widely misinterpreted as
"fifty-page manual for a full-featured business application" or
"inscrutably terse online help." Minimal documentation does not
eliminate the need for the more conventional forms, whose primary
purpose is not to teach but to explain particular tasks and features
just in time.
Jim Purcell
jimpur -at- microsoft -dot- com
My opinions, not Microsoft's
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
