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.
Robin Johnson wants real-world documentation that explains and solves a
problem and doesn't only explain a process.
<<Why is there such a dearth of "solution" based documentation? Everything
seems to be "process-oriented" rather than "results-oriented." Reference
manuals and user guides are fine, but sometimes I'd like to see an example
of the functionality in actual use, rather than "Select-File-Click-OK." Am I
alone in this or do others feel this way too?>>
I understand what you are saying and strive to write the type of documents
you what, but for myriad reasons am not always able to do so. I understand
that my employer pays my salary and sets the standards for my docs. If
management says they want them on Thursday in whatever shape they're in and
I tell them that there will be big gaping holes, at least they can make an
informed decision. But it's management's decision.
"Solution" documentation takes more time and effort to develop. If the
technical writer for a project doesn't understand the topic they are
documenting, then all you will get is "Select-File-Click-OK" because that is
all they can do. A monkey could do that or at least a secretary. As others
on this list routinely mention, it is these writers that make life difficult
for those writers who are competent and can do more than write
"Click-Snap-Done." (Don't confuse this with not having the time or resources
to produce solution-oriented documentation. It is different.) Also the
incompetent ones throw their hands in the air and ask the subject matter
expert to do the work for them and then "clean up" the language.
I would call what you are looking for "use cases." Use cases must be
conceived after you understand who will use the product and why they are
using it. This requires some analysis -- perhaps 30 minutes to develop a
rough sketch or longer for a more detailed idea, but it should be relatively
clear for whom you are writing relatively quickly. There is probably an
infinite number of use cases that you could develop, but you must choose
judiciously, otherwise your documents won't be any better than the
Select-File group's documents.
Granted having some development specs and requirements will help, but
they're not always available. That doesn't mean that the information isn't
available. That's part of being a technical writing...finding the
information. Grab a shovel and start digging. After you have a pile of dirt,
start sifting. Find the nuggets and use 'em.
Minin' for any precious metal....
-Lief Erickson
Lead Technical Writer
MQSoftware, Inc
lerickson -at- mqsoftware -dot- com
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com
---
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.
