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.
I'm in the process of writing something for equally stupendously learned
(if not more so) users ... The product manager (and resident tech
commers) all say that it would take three or more years for me to learn
the details of what they're talking about. And after reading a fair
amount, they're being kind - and I'm a quick study!
Perhaps you are going outside the scope of the document.
My audience is people who write very low level applications that
interact directly with DSP processors. For example (one of literally
hundreds), they use assembler code instructions to define and clarify
the edges of images so they look good when shown on a digital projector.
We're talking very technical stuff.
I - or the resident TCs - don't have the time, space, or ability to
explain how to do this. They have to go to school - EE-type engineering
school if not a Master's program - to learn this stuff. We have to
believe they know what they want to do, and more or less how to do it.
What we're doing is showing them the instructions (i.e. Lego building
blocks) they need to use to craft a program together that does what they
want.
So ... maybe your audience needs to learn the basics of what to do
elsewhere.
As a wholly different metaphor: do you still explain to people how to
click and drag a mouse? We used to do it, but we don't any more because
everyone already knows this ... or they go elsewhere to learn it. It
would perhaps benefit 1/100th of 1% of our audience if we did it, but it
would get in the way of the other 99.99%
My 2¢,
John G
Nancy Allison wrote:
> The "This too" thread (which sounds like a good name for a soap opera about tech writers, since we've wandered into the wilds of television programming) --
>
> Ahem.
>
> Yes, as I was saying, the "This too" thread is currently reviewing the useful role of the clueless idiot. I find this role helpful sometimes, but in my current job, it's of no use at all. Every time I try to get the engineer to think in terms of explaining the significance of his context-free strings of jargon, every time I say something like "Imagine you're explaining this to a bright 10-year-old" or "to a bright college intern" or "to someone who's new to the job" -- he gives me the same response:
>
> "No, no. Not 10-year-olds! No interns! Web services engineers are very knowledgeable, they're not beginners. The reader of this document won't have any trouble with this!"
>
> i finally, finally got him to recognize that there was a time, once, long ago, when he himself did not know this stuff and needed to learn it. And, there was the very first day he ever had the job title of "Web Services Engineer" and had to rely on documents to help him by being understandable. THERE WAS A TIME when he did not know these things, yet was close enough to the technology to be starting a job that required him to master them. AT THAT TIME . . . he would have welcomed a document that explained things clearly.
>
> (At a later date, I explained to the subordinate to whom the Web Services Engineer had delegated the matter, "This text is like throwing suitcases at somebody really fast. They have to catch them and put them in order before they're hit with another one." I was getting a bit desperate. Not sure if the image was really that helpful.)
>
> Anyway, because the readers of this document are stupendously knowledgeable, they don't need anything explained, and they don't mind having suitcases thrown at them, and I should leave the document alone . . .
>
> Is it Friday yet?
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Create HTML or Microsoft Word content and convert to Help file formats or
> printed documentation. Features include support for Windows Vista & 2007
> Microsoft Office, team authoring, plus more.
>http://www.DocToHelp.com/TechwrlList
>
> True single source, conditional content, PDF export, modular help.
> Help & Manual is the most powerful authoring tool for technical
> documentation. Boost your productivity! http://www.helpandmanual.com
>
> ---
> You are currently subscribed to TECHWR-L as john -at- garisons -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit http://lists.techwr-l.com/mailman/options/techwr-l/john%40garisons.com
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/ for more resources and info.
>
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
