Re: What exactly is minimalist documentation?

[Pete Kloppenburg <pkloppen -at- CERTICOM -dot- COM>]

Eric notes:
> 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
quite expensive.

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
Technical Writer
Certicom Corp
Mississauga, Ontario,
Canada
http://www.certicom.com


   If it's about technical communication--post it! If not, don't!
Posts: mailto:techwr-l -at- listserv -dot- okstate -dot- edu
Commands: mailto:listserv -at- listserv -dot- okstate -dot- edu (e.g. SIGNOFF TECHWR-L)
Archives: http://listserv.okstate.edu/archives/techwr-l.html,
	http://www.documentation.com/, or http://www.dejanews.com/
Subjects: JOB:, QUESTION:, SUMMARY:, ANNOUNCE:, or none of these.