Re: Managing Engineers (long)

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

> There's some confusion here. The original issue was developer/writer
> communications....I'd certainly agree that a writer needs subject matter
> knowledge, but that's very different from application programming
> knowledge.

In context I think we can all agree that developer/programmer = SME.  

But just to clarify:
You cannot write an intelligent document unless you understand the subject
matter. If the subject matter is a computer application, then yes, you must
have application programming knowledge. 


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

That is EXCEEDINGLY relevant.  Knowing these technologies gives you an intimate
understanding of how the product works. This lets you anticipate issues,
concepts, and potential ideosyncracies. 

I find it disturbingly humorous that you would defend technological ignorance
as an acceptable and endorsable modus operandi for people tasked for TECHNICAL
communications. 

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

What? Okay, let me see if I understand...

People using a product don't need documentation from a person who is
exceptionally skilled in the design and construction of the product they just
need a writer who merely knows how to use the product.

I'm sorry, but when I read a user manual, I want the author to be 100% in
command of ALL relevant concepts, issues, and technical details. If I knew the
author of a technical document did not understand the intimate technical
details - I'd toss the manual. I imagine this is why a lot of people toss the
manual. Why read something from a person who only has cursory knowledge of the
product? 

> There is a difference between subject matter knowledge and application
> programming knowledge. 

Not if you're writing documents about computer applications. Which is
apparently what you do. I document applications as well.  I am not a programmer
by any means, but I know the intimate, programming details of the products I
document. 

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

No it isn't. Not at all. Understanding how that application was put together is
the ONLY reliable way to truly understand how it works. You're out of your mind
if you think you can ever really know how things work without knowing how they
were built? You can't. It's impossible. 

Andrew Plato 



__________________________________________________
Do You Yahoo!?
Yahoo! Shopping - Thousands of Stores. Millions of Products.
http://shopping.yahoo.com/

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