Re: Managing Engineers (long)

[mpriestl -at- ca -dot- ibm -dot- com]

Andrew Plato:
>As a ***TECHNICAL*** communicator, ignoring the technical details makes a
>writer less capable. It diminishes a writer's capability to effectively
>communicate with an audience.

Since my audience couldn't care less what language the application is
programmed in, how does my lack of Java programming skill affect my ability
to communicate with them?

>In my opinion there are three aspects to a decent writer (in order of
>importance):
>
>1) Command of the subject matter.
>2) Command of the reader's needs.
>3) Command of language.
>
>If a writer is missing any of these parts, he/she is lacking and not
capable of
>communicating effectively.
>
>Basically, Michael, your assertion is that #1 isn't important. You can
slip by
>with #2 and #3.

No, my assertion is that if I don't need to write about it, it's not my
subject matter. The language the application is programmed in is not the
language it should be documented in. You should understand the *subject
matter*,yes, but the subject matter of a FrameMaker manual is not how to
develop cross-platform C/C++ applications, even though that's what the
developers of FrameMaker did. You seem to think that a FrameMaker expert
could write a decent FrameMaker manual, yet simultaneously maintain that a
writer should understand as much about the application as the people who
developed it. How many FrameMaker users out there could develop an app like
FrameMaker? And yet many of them could certainly write a good FrameMaker
manual.

Your assertion appears to be that a manual, whether aimed at mortgage
brokers or FrameMaker users or compiler users, should include information
about how the product was developed, including the language of the
application (C++, Java, assembler, etc.), what distributed architecture it
uses (CORBA, EJB, etc.), what string functions the developer uses for field
validation, what transaction security measures are called (byte code
please) when dealing with third-party interfaces, and so on.

What have you just written? It's not a user guide, that's for sure. Why
would anyone pay you to write that book? Who reads it, apart from your
developers, assuming they're narcissistic enough to bother?

Do you understand what I mean by subject matter now? Do you understand why
I have a problem with your use of the phrase?

>Yes. You can. Many tech writers have merely a command of language and a
weak
>command of the reader's needs. However, I assert that these are less
qualified
>writers that those that can handle all three.
>
>There is no excuse for ignorance.

Give me a break. The ability to develop an app differs from the ability to
use or understand it. There are perfectly good excuses for ignorance, like:
"That knowledge is totally irrelevant to doing my job". How's your command
of sanskrit? What's your excuse for your ignorance? For extra credit, what
was Socrates's excuse for his ignorance?

>I also assert that the preponderance of these types of writers are why so
many
>engineers roll their eyes and sigh when they have to work with a technical
>writer. They are sick and tired of people who defend their ignorance as if
it
>were a recognized skill.

You're polarizing the issue. If a writer is documenting for a technical
audience, they should absolutely have that technical knowledge (as I have).
If a writer is documenting for a non-technical audience, then that
technical knowledge is irrelevant. If the programmers insist on technical
knowledge in their writers even when it isn't relevant, then they are being
tech snobs, and boors to boot.

I'm curious - can you tell me what kind of software you are currently
documenting? It might help me understand why you continue to conflate your
user's subject matter and your programmer's subject matter.

>Andrew Plato

Speaking on my own behalf,
Michael Priestley
IBM Toronto Lab



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com or 800-448-4230

---
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.