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.
> 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.
I agree (!), but poor focus and weak structure can be the result
of numerous things -- maybe shallow subject-matter knowlege,
maybe failure to analyze the audience need, maybe
I certainly share Andrew's dislike for those menu-oriented
approaches to user-guide oraganization: "This menu
contains these commands"; "This toolbar contains these
buttons"; "This button does this, that button does that";
"This window has these things in it"; and so on.
This is a very common way of "documenting" an interface,
and almost never the best way, especially when it is a
poor substitute for task-based instruction. It is an exercise in
list-making and cataloguing. It's like writing restaurant reviews
while sitting at home reading menus and advertisements,
and never actually ordering a meal.
Usually, the better way is task-oriented: "To achieve this result,
follow this procedure." And to do that properly requires an
undertanding of what your users want to achieve.
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.