Re: Minimalist or low-level?

Subject: Re: Minimalist or low-level?
From: Brad Jensen <brad -at- elstore -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 4 Mar 2002 22:03:15 -0600


----- Original Message -----
From: "Lisa Wright" <liwright -at- earthlink -dot- net>

> 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.

I guess no one uses print docs anymore, but if you are scattering hyperlinks
all over the place they had beeter be meaningful.

Poor documentation is defined as saying something one time in one way in one
place.

Most docs these days are searched help-file style, and if you have a mental
construct of them as a serial presentment you will fail your readers. Say it
again, say why it is important again, say it a different way, and show an
example.

> 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.

Again, with electronic docs that don't cost by the page, it's better to be
detailed , because some one is going to need the details.

> 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.

If you are going to write spare docs, you better add some explanatory links,
and explain them in text (not just at the front of the doc).

> Part of the reason that so much documentation is dumb is because we
> waste time repeating ourselves when it isn't necessary.

As a user, I have never found myself annoyed by too much explanation. This
is particularly true of subjects requiring technical documentation.

> Good grief, I
> just cut 27 pages out of a 72 page manual during a re-write of a
> previous writer's work.

Really what should be done is to charge all tech support calls back to the
tech writers budget. It isn't just that the tech calls cost money, it's that
each one is a failure of the product.

Brad Jensen


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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.


Follow-Ups:

References:
RE: Minimalist or low-level?: From: Lisa Wright

Previous by Author: Re: The Big Lie (was 'Are You a Writer?')
Next by Author: Re: Minimalist or low-level?
Previous by Thread: RE: Minimalist or low-level?
Next by Thread: RE: Minimalist or low-level?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads