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.
Subject:Re: What exactly is minimalist documentation? From:Pete Kloppenburg <pkloppen -at- CERTICOM -dot- COM> Date:Mon, 27 Oct 1997 17:34:53 -0400
> The question to ask yourself before you dive into
> the real minimalist school is "does my audience
> want/need to _learn" this stuff, or should they
> refer to the docs, do what they need to do, and get out.
and later warns:
> anyone considering minimalist
> approaches should _carefully_ read Carroll's works (in
> the original--not someone else's synopsis)
> with an academically critical eye and see if it really applies
> to their situation.
I agree wholeheartedly. I just got back from the IPCC '97
conference in Snowbird, Utah, where Carroll himself gave a
quick and dirty explanation of minimalism.
Now, most of what I'd heard about minimalism came from this
list, and it didn't jive too much with what Jack was talking
about, but no mind. What immediately struck me was that I
couldn't apply minimalism to my situation. Jack says that
minimalism is grounded in the realm of tasks. But I document
crytpographic programming libraries. There aren't any tasks
to speak of, other than don't screw up. Jack says that you
should focus on error recognition and recovery. But it's
actually quite difficult to spot cryptographic errors, and
really, you'd rather not allow your users to make them at
all. Make a boo-boo implementing our stuff and it can be
So I'm going to focus on other aspects of Carroll's work,
which I tend to admire. For instance, minimalism recommends
providing the user (reader) with opportunities for further
reading and learning, and we'll certainly do that. And instead
of drawing the reader in with problem-solving situations, we'll
do it with narrative (which lets us provide the answers and
eliminate the potential for unrecoverable user error).
So no, don't jump on to minimalism as a cure all, because it
certainly is no such thing. Take the time to reduce Carroll
to first principles, then apply your own logic to come
up with something that fits your situation.
Pete Kloppenburg - pkloppen -at- certicom -dot- com