Re: Managing Engineers (long)

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

Andrew Plato replied:

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

Only in a trivial sense. I think there are a number of "subjects" involved
here. There is the subject the application addresses (the problem domain),
and then there is the subject of the application itself (the solution
domain). A good technical writer needs to understand the problem domain in
depth, or they won't be able to write task-oriented documentation because
they don't know what the tasks are. A good technical writer also needs to
understand a _portion_ of the solution domain: the user interface. In ideal
circumstances, the technical writer, along with a human factors expert and
a few expert users, actually designs the user interface at the same time
they write the documentation.

Now, a good UI designer is a definite specialist (a subject matter expert
in human factors), but rarely are they specialists in programming or even
the problem domain. Usually there is a team of programmers to develop the
application, and a bunch of users who get interviewed and tested to direct
the design of the application.

I guess everyone is a subject matter expert, if you don't care what the
subject is.

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

The subject matter is a "computer application" in only the most trivial
sense. The subject matter is actually the use of the application to solve
problems that the user has. If you don't understand those problems, it's
impossible to write intelligently about the application.

In addition, most of the computer application is never surfaced to the
user. Does a mortgage broker care what kind of functions the programmer
used to validate that bank account numbers are the right length? I submit
not.

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

If you, as a writer, have the choice between taking a brokerage course, or
taking a course on EJB development, which knowledge do you think will most
improve the documentation?

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

I find your stance equally disturbing and humorous. You seem to think there
is only one kind of technical and one kind of ignorance. Knowledge is not a
boolean. Given how much time I have for education, I'd rather spend it on
subjects that benefit my users than subjects that make you happy.

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

No "merely" about it. I know more about using my products than 90% of my
developers. They know more about implementing their piece of the product
than I do, but I have the big picture, and the user understanding, or I
couldn't write samples, scenarios, and end-to-end tutorials.

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

Compiler design is utterly irrelevant to a C++ compiler user. If you, as a
user, are designing a compiler, then you certainly aren't doing so in C++.
EJBs are utterly irrelevant to a mortgage broker using an online
application. If they search the help and get hits on "EJBs", they will
legitimately ask why the company didn't hire a technical writer to either
filter out that techno-gibberish or turn it into something meaningful.

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

As I wrote above, my knowledge of the user interface is more complete than
most of the developers'. My knowledge of the user domain is also more
complete. My understanding is hardly cursory.

If you're spending so much time learning programming details, when do you
find time to learn what the user wants to know? Or do you just write a
bunch of API docs and consider your work done?

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

Good for you. I applaud your initiative. And to the writer who documented
the online brokerage application, I applaud their initiative in taking a
brokerage course. I suspect their education was more well-spent than yours.
What do your users do again?

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

How do users do it? Compiler users use compilers without knowing assembler.
People create web pages without knowing how Netscape works. People use bank
machines without knowing OS/2, or VM, or DB2. Are they out of their mind?

If you have to read source code to know what's going on in your
application, you've got major process problems. With new applications, I
spend a fair bit of time talking with developers, attending user sessions,
and reading up on the area. With established applications, I track defect
and feature status, and do follow-up interviews as necessary. Since I've
got signoff on all user interface files before they ship to translation,
very few technical changes slip by me (there's a process suggestion that
addresses your original issue). I don't have the time or the inclination to
read a bunch of source code when I don't need to.

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