Re: techwr-l digest: May 28, 2003
It isn't that documents are "completely wrong," they're just not wholly
accurate. Actually, what I see a lot more of these days is poorly focused
documents. There is a tremendous amount of energy poured into sections of the
document that describe simple commands and menus, and then detailed technical
information is thrown into a poorly formatted appendix. A clear indication that
the author did not understand the material, and was unwilling or unable to
learn it.
Not necessarily the correct conclusion. There was a period in the late '80s that produced bodies of research about categories of information, and their importance to the user. The "Overview/Deep Understanding" school lost, and the "Procedural Information" school won. In other words, it suddenly became vogue to present procedures, and leave the deeper knowledge out of the picture altogether. Solid rules were established, like:
* Active voice, only
* Begin each procedure with "To do xyz..."
* Organize by task domains, and not alphabetically
* Other???
Some of these are good ideas. But I (think I) agree with Andrew on this point - we have thrown out the baby with the bath water. I am a firm believer in the value of an over-arching *model* of a product, problem, or domain. I personally want to puke when all I get are rote instructions.
Does this mean the writers don't understand the material? Not necessarily. It could mean that the pubs manager doesn't understand the material. It could mean that the pubs manager and/or mktg. weenie hates the product (common in mergers, for example). It could mean that the company doesn't value the docs very much, and only wants the bare minimum. In each of these cases, providing a TOC chock full of entries that begin with the words "To do xyz..." is bound to please. Then the truly passionate writer is forced to beg for a measly appendix - as few pages as possible, please - where he can put some solid information. (I've been there, and I have the T-shirt to prove it.)
--
Chris Despopoulos, maker of CudSpan Freeware...
Plugins to Enhance FrameMaker & FrameMaker+SGML
http://www.telecable.es/personales/cud/
cud -at- telecable -dot- es
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Robohelp X3, from eHelp, lets you quickly and easily create professional Help systems for all your Windows and Web-based applications, including Net.
Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.
Order RoboHelp today: http://www.ehelp.com/techwr-l
---
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.
Previous by Author:
Re: Sloppy writing, sloppy thinking?
Next by Author:
RE: PageMaker
Previous by Thread:
re Set up to Fail
Next by Thread:
Re: techwr-l digest: May 28, 2003
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads