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