RE: Minimalist or low-level?

["Lisa Wright" <liwright -at- earthlink -dot- net>]

Scott,
First of all, I am firmly in the minimalist camp. That said, I think if
the procedure is truly a one-step thing (select File-->Open) vs. a
one-step description of the process (open the record), I don't see much
difference and your approach is probably more clear.

However, there are some very legitimate business reasons to look at how
you're explaining repetitive procedures. You don't mention if you're
writing for online or print docs, or whether your docs are being
translated. If they're being translated, you need to look at the cost of
translating the same text over and over. I don't agree with Geoff P. I
think catering to the "lowest common denominator" of your users is a
waste of time, effort, and company $$$. (Does yours have any to spare
right now?) Focus your energies where they'll have the most impact.
Unless you know that the majority of your users have never seen a mouse
and monitor before, don't assume that they need to have their hands held
so much. 

I use the following rules for my own work:

1. The 80/20 rule. The fact is that probably *very* few of your users
need to be told that "Open" can be found under the "File" menu. Unless
you are writing for truly new computer users, i.e., people transitioning
from an entirely different field where computers would be unheard of.
Write it once on the off chance that someone needs it and refer to it
when needed.

2. Consistency. If you write the procedure for "Opening a record" one
time and cross-reference as needed (either through hyperlinks or page
#s) then you don't have to worry about whether you said it the exact
same way the 500 times that you said it. Reference it and move on to the
important part of the process you're trying to describe.

3. Focus on the important parts. Most of these procedures aren't about
opening the record. They're about what to do with the record once it's
open. Don't spend 10 minutes (exaggeration, maybe, though I've seen it)
trying to get them to the meat of the procedure.

I agree with John; I seriously doubt that your users are going to be
insulted by whatever you do, barring calling them stupid. But one of the
keys of minimalism is to give the reader *only* the information they
need, when they need it, and give them the *means* to find more.

Part of the reason that so much documentation is dumb is because we
waste time repeating ourselves when it isn't necessary. Good grief, I
just cut 27 pages out of a 72 page manual during a re-write of a
previous writer's work. Everything I cut had been said a dozen times
when once +hyperlinked cross-reference would do much better. You
couldn't tell what this manual was about because you were always
searching for the frickin' record! Plus, because the procedures were
copy/paste, they were included where the weren't appropriate. Dumb.

Hope you figure out a good compromise. Take care,

Lisa 

-----Original Message-----
On Behalf Of Parsons, Scott
Sent: Monday, March 04, 2002 4:58 PM
To: TECHWR-L
Subject: Minimalist or low-level?


Hi,
My co-workers are minimalist procedure writers and I'm a low-level
procedure writer. That is, I write "On the File menu, click Open" while
they write "open the record." I am currently weighing the better method
of writing: minimalist or low-level. I don't have a true knowledge of
our target audience, but my co-workers have assumed they are skilled
users and would be insulted by such low-level writing. We all write for
the same project, so it's crucial we remain consistent. I've read
through the archive, and some say that this decision is best made when
you know your target audience. Since this is unlikely, I've assumed our
target audience is a general user. Somewhat familiar with our system,
yet new to whatever concept or procedure I am writing. In addition, I've
already written low-level procedures (so as not to assume my target
audience is well versed) With that said, I've embarked on a quest to
convince myself and perhaps my co-workers that low-level procedures are
best. However, I need supporting data. Can anyone provide me with a
reason why low-level writing is better than minimalist? Or, vice-versa?
Thanks, Scott 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.