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.
> Perhaps, if you don't know your subject and are struggling to explain a topic
> that you don't fully understand. In that event, you shouldn't be making the
> attempt. Conceptual information may be more valuable under certain limited
> circumstances, but most users want to know how to *do* something.
If a writer does not know the subject, then they shouldn't be writing the
documents in the first place. Likewise, all employers should require their
technical writers to be well-versed in the technologies they document.
Furthermore, I firmly believe users want (and need) to know WHY they are doing
things. When you accurately document the "why" and "what", the "how becomes
almost incidental. If you understand why things work they way they do, then how
to make them do that is relatively straight forward.
> That assumes the software is well-designed and intuitive, and that users have
> the luxury of spending five minutes reading about concepts. A good procedure
> introduces the steps in a process with just enough conceptual information to
> prepare the user to perform the task.
I would argue that concepts are MORE important when there are design flaws,
since you can't fall back on simplicity as a guiding factor.
Moreover, what is "just enough" conceptual information? If I flip through most
documents, "just enough" seems to be interpreted as "practically none." A
paragraph here and there, with miles of procedures in between.
> Maybe that's because most users of documentation want to know how to use the
> software, not how or why it does what it does.
Again, I disagree. Most users DO want to know why. Perhaps the absolute bottom
of the barrel bureaucrat types only care for the raw procedures. But given the
choice, users do want to understand the technologies. Moreover, neither item is
mutually exclusive. Concepts don't have to intrude upon procedures. The
bureaucrat types that just want instruction with no context can flip past the
conceptual stuff. The people that like to know why, can read that. The
inclusion of conceptual material does not degrade the document in any way (it
of course makes it better.)
> You should hear what they say about yours!
I am not going to respond to that remark.
Andrew Plato
__________________________________________________
Do you Yahoo!?
Yahoo! Shopping - Send Flowers for Valentine's Day http://shopping.yahoo.com
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at 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.
