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.
""Martin R. Soderstrom"" <scribbler1382 -at- yahoo -dot- com> ...
> | Same with programming manuals: If you want to write a manual for a
> | programming language or a fundamental programming tool or non-trivial
> | API, you need to be a programmer; there's just no way around it if you
> | want to create a decent manual.
>
> That's nonsense. What you need is an understanding of how programmer's
> =think=. Sure, you're going to need some basic understanding of
> technologies and practices, but no where near the depth to which an actual
> programmer would. In fact, that can be a hindrance.
Here we go again...ignorance is a benefit.
Martin, it is absolutely, 10000000% impossible for a human being to write an
authoritative document about a complex technology or programming language without
*some* in-depth knowledge of the topic. In many cases, a good writer must have a
considerably more in-depth and broader knowledge than the SME since they must
integrate these complex concepts with many other disciplines. And the only way
you can do that with ANY degree of success is if you have taken the time to learn
and digest the technology.
Without question, the single largest reason technical documentation sucks is
because the people tasked with producing it relied entirely on the good graces of
engineers who had virtually no stake in the successful execution of that
documentation.
Perfect example: if an engineer walks up to you and says "our software does not
interface with any kernel level operations." would you have the knowledge to
confirm that? So you slap it in your document and it turns out to be entirely
false. Now your document has a glaring inaccuracy because you didn't have the
knowledge to confirm or analyze that engineer's data. Customers read this and
laugh at it because they know its BS. They throw your product in the trash and
purchase a competitors product.
And since the writer is entirely responsible for the document, this oversight is
squarely the writer's fault. In this example, the writer helped the company lose
a sale because he lacked the ability to analyze the information handed to him for
accuracy and relevance. Sure, the engineer wasn't any help either. But that
doesn't excuse the writer from verifying his sources. A fundamental concept
taught day one in any journalism school.
If you want ownership of your work, you have to have ownership of the knowledge.
Otherwise, you're just editing other people's text, and that isn't writing.
Andrew Plato
__________________________________________________
Do You Yahoo!?
HotJobs - Search Thousands of New Jobs http://www.hotjobs.com
Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save! 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.
