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.
Subject:Re: Active Ownership From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Wed, 7 Jul 1999 16:54:48 -0500
> With all that reality exposed, however, the value-add provided by TW is
> really locked up in the idea of minimizing the time it take to understand
> the content. That content may be in the form of a graphic, a table, or
> That content should have an easily understood information architecture, be
> accessible, and be reader/role centric. Every paragraph we write costs the
> customer money to read. Every long-winded, theoretical discussion that
> delays getting work done, costs the customer money and eventually costs
> company a customer even though the user is now an expert.
I agree with "minimizing the time that it takes to understand the
content". I also agree with the comments on information architecture.
However, I find the, "manual has too much info, so, it will eventually cause
the customer to go away" observation quite an exaggeration. Do you have any
metrics to support this claim? What percentage of customers have stopped
using a product because the manual was too large?
I guess I see the statement as applicable to some documentation
(say, an operating manual for a toaster) but not to others (such as
instructions for developing an application with an API toolkit). Not all
documentation is , "Do Step 1, see this result, Do step 2, see the next
result, etc...). Some documentation must train the user in the theory of
how the processing works so that they can set parameters to achieve the
desired results. Documenting every possible combination is not always
possible. If the user is presented with 10 controls and each control has 10
possible settings, then how many possible combinations/results are there?
Instead, if the user understands the process they can save time by
eliminating non-applicable combinations or trying each of 1000 procedures to
find the correct one.
> Read this as,
> costs the vendor, our employer, its investment in its increasing return.
> And, content that makes the user to much of an expert likewise drives up
> support costs and eventually drives the customer to some other product
> suitable to that expert's craft use context.
And the flip side is that not enough documentation leaves the user
learning by "trial and error". Again, it depends on how much of the process
is handled by the product and how much is dependent on user choices. Better
to give the user more than enough information if qualitative decisions are
required by the user than to leave her/him guessing. In some cases, what
worked simply in one instance of the process may not work in the same manner
when the user must make modifications for the next instance of that process.
> More doc is rarely the
> solution. The right doc is the solution. And the right doc changes over
> lifecycle of the product as it moves from market to market, and audience
David W. Locke
This goes without saying. The "right" anything is usually the best
solution. Now all we need to know is what is "right" for every
learner/reader. Given all the ways in which people learn, a single "right"
document may be more ideology that practicality. Some people are visual,
some are concrete, some are abstract, some are auditory, some make
analogies, and so forth. What one "right" document addresses all these