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.
> Basically, the review left off one of the most important aspects of
> technical communication--the actual communication of information. Now,
> even if the reviewers knew nothing about the subject matter, they should
> still
> be able to get a feel for the logical presentation of the information.
> If I recall, he had to fill out a bunch of info about the audience and the
> purpose of the manual. They could easily see if the manual lived up to
> those areas. Instead, the judging was based entirely on superficial
criteria.
A lot of STC folks like to chant "we can't evaluate content." Personally, I
think that is a cop-out. They don't WANT to evaluate content because that is a
lot harder to do.
Anything complex can be analyzed for its value if a logical, rational, and
intelligent approach is used. Key questions need to be asked like:
Does this make sense?
Is it educating me on the important issues?
What are those important issues? (Something easily answered by a little
research)
Is the information logical? Does one concept lead to the next?
Does the writer draw conclusions from the facts and methods?
Are there unstated assumptions, like "best practices"?
Just this week had to admonish one of my consultants for failing to structure
his information in a rational manner. He was explaining security issues for a
customer, but referencing these "industry best practices" that were never
explained or discussed. As such, he was leaping to conclusions about security
before he had presented the evidence and methods to back up those conclusions.
This was a classic case where HE understood something very well, and his
assumptions we're based on his knowledge. But he never stated these
assumptions. As such, his conclusions did not follow from the data. They
followed from an "unstated assumption." Bad writing.
When I read a document, I look for a logical presentation of information,
something like this:
- Premise/Assumptions
- Facts
- Methods
- Conclusions
- Inference on those conclusions
Or in other words:
- Why does it exist.
- What can it do.
- How does it function.
- What can I get out of it.
- What does it relate to.
Which are merely an extension of "The Five Golden Questions" stated before:
1. What is it?
2. What does it do?
3. What is its purpose?
4. How does it work (or how does it do what it is supposed to do)?
5. Why is it relevant?
Most writers focus almost all their energy on the "how" when they document
procedures. They explain how to do things, but not WHY you're doing those
things or what the value of those things are. The other crime I see a lot of is
failing to establish key concepts. Writers assume their audience understands
what they are doing, and as such just documents the raw procedures to do the
work.
Part of the problem here is the obsession with procedures. Go pick up one of
the "award winning" STC manuals and you'll notice something. Pages and pages of
numbered lists with scant descriptions. And most of the time you see laughable
constructs such as:
23. Type your name into the Name field.
There's some f-ing insight for ya.
As such, these STC reviews are nothing more but feedback loops. Writers who
can't handle content, telling other writers that content isn't important. The
writers getting reviewed hear this and go back to their jobs thinking "wow, I
need to focus more on single-sourcing, font selection, and persona analysis."
When in fact, these issues are, as we all know, of marginal consequence in the
overall value of a document. They would be better off to totally ignore such
issues, and work on understanding the technology.
The best review you'll ever get is from your customers. Or if you're lucky,
you'll have a nitpicky engineer who reads everything and slashes you to bits
over the content.
These STC reviews may be fun to see what other writers think. And if you're
lucky, you'll get an a**hole like me who will hold you to the proverbial
content fire and do deep, rhetorical analysis of your work. But more than
likely, you'll get some marginally useful advice from a person only looking at
the superficial aspects of your document.
Andrew Plato
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now. http://mailplus.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.
