[Elecraft] Parting shot

[Edward R. Cole]

Good point.  In fact, in my early work history as a tech writer for 
Hughes Aircraft, we had a minimum of three people involved in editing 
or reviewing  text.  I would write it, some one would review and 
edit.  I would review that and correct anything I thought was 
needed.  It went to a third reviewer and back to me and then the two 
others would again review and so it would go.  Why it would take 
3-weeks to write a page.

I was an engineering writer, so I was in charge of content (technical 
accuracy).  But one of the best experiences was a week long seminar 
put on by our Phd english expert on how to write documentation.  It 
followed me thru the rest of my career, where the ability to write 
for comprehension mattered more than most engineers would admit.

Yes, I did technical work, but often I was asked to explain 
(quarterly reviews) or write procedures for the un-technical 
personnel.  An example I often love to tell is when I was a college 
student taking FORTRAN programing class (1965).  The instructor was a 
complete disorganized idiot.  That is not how you teach programming 
(a logical subject).  Fortunately, the text book was great.  I put 
together a 30-page outline of the course for teaching myself.  Once 
that was known in the class I had several request for copies.  I like 
to think I helped get several thru that class.  A case of the 
recently learned teaching better than the "staff".  BTW the "prof" 
started class by taking his old battered briefcase and dumping the 
contents onto his desk, sorting thru a heap papers for his class 
notes...ugh.  But the perspective of the non-expert who has recently 
learned a topic having better delivery of instruction than the 
"expert" is good one to realize.  Same approach of doing user evaluations.

Some times targeted documentation is better than "does all" type.  A 
user manual; A reference manual.; An installation manual; and a 
service manual.  But that takes human resources to generate.  BTW I 
had a Navy tech once tell me that all they used from our tech manuals 
were the diagrams! ;-)

I think the K3 handbook is technically pretty good, but maybe could 
use some rearranging.  Topics are segmented throughout the 
document.  A good index is vital to any good manual.  K3 index is 
pretty good, but wish I didn't have to use it so much.

---snipped
There is this other thing we continually forget, anyone technically
qualified to design something is hugely UNqualified to write the doc
for it.  Only edit after the writing for factuality.  Doc on something
needs to be written by somebody who has freshly learned how to use
that something starting from a position of ignorance.  The most
important thing in doc writing is understanding NOT UNDERSTANDING.
The engineering staff is usually completely opposite, they've never
NOT understood how that something works.  They MADE the d**n thing.



73, Ed - KL7UW, WD2XSH/45
======================================
BP40IQ   500 KHz - 10-GHz   www.kl7uw.com
EME: 144-1.2kw, 432-100w, 1296-testing*, 3400-winter?
DUBUS Magazine USA Rep dubususa at hotmail.com
======================================
*temp not in service