RE: Damnit Jim, I'm a Writer, not a Programmer II: The Wrath of K ahn

[KMcLauchlan -at- chrysalis-its -dot- com]

Peter [mailto:pnewman1 -at- home -dot- com] said:

>for you non-programmers. try to decipher the meaning of a 
>statement such
>as 
>
>fprintf(urt, "%f.6 %s " , dr, (i=0;1+%r\d;++i));
>
>Without a basic understanding of the language, few could tell whether I
>have made a syntax error, never mind the meaning.

Er... fine...

All you list-members whose job description 
includes a significant amount of software QA, 
please stand up.

Now, speaking from [what would appear to be]
the opposite camp:

When I include a chunk of code in a toolkit 
or API doc, I don't make it up. I get it from 
the development team. I copy and paste, precisely 
so that I won't introduce any thumb-generated 
errors.

I usually glance over it to see that the sample 
addresses the topic of the current document section 
-- say a discussion of a group of functions or 
of a sample implementation of a "real world" 
activity. In other words, is there enough here 
to show a customer/developer what direction s/he 
out to be taking, to meet a certain kind of requirement
or task?

I feel I need to know enough about C and C++ to avoid 
using some words in general text where those words are 
also terms with specific meanings within the languages.
I (and my employer) benefit from my having a passing 
familiarity with what the code looks like. Neither of 
us really thinks it's worthwile for me to spend 
our time and their money learning to code in C++ or 
JAVA, to even the shaky standard of our rawest novice 
programmer.

I've got a requisition submitted, to have my registration, 
travel and accomodation paid for the FrameUsers 
/c/o/n/f/e/r/e/n/c/e/ Workshop this year, and it'll 
probably be approved. Last year, it was the STC 
Convention.  If I requested some training or some 
materials to learn more about one of my tools, I'd 
get that, as well.   I would not get approval for 
company time and funding for a programming course, 
nor for attendance at a SW-designers convention.

Similarly, none of our programmers/developers is 
going with me to FrameUsers, nor are they likely 
to get sent to a FrameMaker or Illustrator course, 
nor a workshop on Indexing and cataloging, nor 
anything on Acrobat publishing techniques.

Funny how that works.

When it turns out that there's a problem with 
multi-threading with our product on one of the 
supported platforms, I don't really need to know 
(nor would I benefit that much from knowing) the 
character-by-character explanation of the problem 
and eventual solution. I do know what multi-threading 
is (though I couldn't program an application to do 
it, to save my life) and I can express the concept 
in the right words when I tell our customers the 
suggested workaround. Without knowing the tiny 
detail of each case, I know generally what compiler 
and library incompatibilities are, and can write 
sensibly about either the condition or the fix/
workaround. I can write usefully and comprehendingly 
about driver conflicts and the idiosyncracies of 
getting software to work on various platforms, 
though I leave it to somebody else to actually 
figure out what's wrong THIS time, and to give 
me the gist of what I should convey in the docs.

I can ask sensible questions, and I can ask dumb 
ones. Fortunately, most of our developers receive 
the e-mail threads from our Customer Support group 
(for the same educational reasons I do), and realize 
that my generalist knowledge often exceeds the 
programming and operational knowledge of some of our 
customers.  
It turns out that most of my "dumb" questions weren't 
so dumb after all.

Furthermore, I'm not Product Verification or 
Software QA, but I've been known to break the 
product when investigating it, or to ask embarrassing 
questions that resulted in re-work. But that's all 
incidental to learning what the product does, how to 
make it do it, and how to explain that to others.

The company must like something about what I 
do. They keep paying me. 
They might even pay me more if I took some 
courses, demonstrated that I was now a programmer, 
and worked my way up the developer ranks. But, I 
don't want to write code for a living, and if I were 
to change career paths, the company would then need 
to hire someone to do what I do today.  Even for us 
generalists, ain't specialization, and the division 
of labor, a wonderful thing?

YMMV

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


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