Re: Managing Engineers (long)

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

Andrew Plato:
>If you can't or won't engage SMEs in a thoughtful technical conversation,
>then they aren't going to trust you to adequately communicate the design
>of their system. Imagine if somebody walked up to you and said they
>were going to write a detailed user manual on FrameMaker, but had NO
>idea how to use the product or even what it could do (and had no intention
>of learning). Would you trust this person to write such a manual?

Me:
>Imagine if somebody walked up to you and said they were going to create
>a complex piece of software based on an environmental report you
>just published using FrameMaker, but had NO idea how to use FrameMaker
>or even what it could do (and had no intention of learning). Would you
trust
>this person to write such a piece of software?

Andrew Plato:
>That's an absurd comparison and your translation is incorrect.

Me again:

There's some confusion here. The original issue was developer/writer
communications. In your first sentence quoted above, you switched from
referring to developers to SMEs, and I didn't even notice that until now.
My translation would have been accurate if we were still talking about
developer/writer communication, rather than SME/writer communication. Given
that I have no clue why you suddenly switched to talking about SMEs, my
confusion is understandable. Please explain what the SME is doing in your
original sentence. Do you think "developer" is synonymous with "subject
matter expert"? I'd certainly agree that a writer needs subject matter
knowledge, but that's very different from application programming
knowledge.

I'm going to give up on the whole analogy thing, since it's hopelessly
muddled at this point.

I wrote:

> My point being: someone's credibility should not be gauged by their
command
> of irrelevant knowledge. Knowledge of the audience's domain is what's
> important for a writer, not knowledge of the programmer's domain. The
only
> exception to this is when the audience's domain is programming.

Andrew Plato replied:

>I could not disagree more.  It is foolish, even dangerous, to think there
is
>"irrelevant" knowledge.  If you're documenting some product or technology,
you
>should know as absolutely much as possible about it. There is absolutely
no
>excuse for technical ignorance. Credibility as a technical writer
absolutely
>hinges on a person's ability to consume, digest, and accurately explain
>technical concepts.

There certainly is irrelevant knowledge. Knowledge of EJBs and
transaction-based persistence models is completely irrelevant to
documenting an online mortgage broker application.

>Regardless of whether you are writing for programmers or monkeys, you
should
>have detailed technical understanding of what you're documenting. It is
>*completely impossible* to document a product or technology intelligently
if
>you do not understand how it works or how it was built.

Bull. I've documented C++ compilers and linkers without understanding how
to develop a compiler. Developing compilers is an extremely specialized
skill. I certainly know how to _use_ a compiler, but how to write my own?
Not a clue. And why should I care, since none of my users care?

I wrote:

> That said, I agree that developers are more likely to respect you if you
> have a clue about what they're doing. I just don't think it's fair or
> logical.

Andrew replied:

>Its absolutely fair and logical. Why should *anybody* trust you as an
author if
>you are unwilling to become an expert about your subject matter.  Would
you
>want to read a history text book from and author who said "oh, I don't
really
>need to learn about all those wars and stuff. I'll just make sure we use
the
>correct fonts and tables."

There is a difference between subject matter knowledge and application
programming knowledge. You insist on confusing the two. My subject matter,
for example, is currently database schema design. The tool is written using
a proprietary set of Java GUI classes. Do I need to understand those
classes? Do I even need to know Java programming? No! I need to know how to
design tables, I need to understand keys and views and aliases, but Java
GUI programming is entirely irrelevant to my task.

Andrew again:

>If you are unwilling to talk tech with engineers, do not be surprised if
they
>are unwilling to talk doc with you.

I get along fine with my developers. If you can't tell the difference
between an engineer and a subject matter expert, don't be surprised if you
get into more completely pointless arguments.

>Andrew Plato

Speaking on my own behalf,
Michael Priestley
mpriestl -at- ca -dot- ibm -dot- com
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.