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.
Many popular or merely trendy techniques are applied by rote all too
often, to the detriment of common sense. We have seen how many may not
fully understand Carroll's concept of "minimilism".
Another, and a pet peeve of mine, is the wide variety of poorly
executed use cases.
One example that is unforgettable for me was when I was assigned to
ducument a new feature for a Nortel switch some years ago (obviously,
before they imploded). The engineering document had six separate use
cases, complete with tables and diagrams...yet it was completely
confusing. I struggled with it for hours to gain some clarity as to
the meaning of it all--it seemed illogical, somewhat contradictory
where it wasn't completely duplicative.
I diagrammed everything on a white board--putting each use case in a
different color. For nearly two complete working days, I struggled to
understand why it was such a convoluted explanation for what I
understood to be a fairly simple feature.
I even called the engineer--in India--to try to increase my
understanding. I realized that while he apparently was very good at
coding, his English was as arcane in speech as in his writing.
At last, comprehension began to dawn. The problem was mostly that he
was trying to stretch the feature explanation into every possible use
case he could--even though when it all came down to the essence, it
just wasn't so complicated after all.
The resulting document shrank the explanation of the engineering
document down from about thirteen very confusing pages to two, the
diagrams and tables from six of each to one of each. The diagram,
moreover, had four blocks connected in series.
The engineers of the field implementation unit--who were charged with
installing new software versions at selected customer sites to test
them in the field, told me they "finally understood" what the new
feature was all about.
I, too, spent much of my career alternating between marcom and tech
pubs. Both areas are occasionally known for rote application of poorly
understood concepts. The attempt to be "leading edge" often results in
frustration for all concerned...especially the poor customer.
David
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
