[Elecraft] Parting shot

[Phil LaMarche]

Suggestion......RE-write a chapter of the manual and send to Wayne.  He
might want you to do the rest.  Just an idea because of your back ground.

Phil

Philip LaMarche
 
LaMarche Enterprises, Inc
Phil at LaMarcheEnterprises.com
www.LaMarcheEnterprises.com 
 
727-944-3226
727-937-8834 Fax
727-510-5038 Cell 
 
www.w9dvm.com
 
K3 #1605
 
CCA 98-00827
CRA 1701
W9DVM
 

-----Original Message-----
From: elecraft-bounces at mailman.qth.net
[mailto:elecraft-bounces at mailman.qth.net] On Behalf Of Edward R. Cole
Sent: Friday, December 10, 2010 2:24 PM
To: Elecraft at mailman.qth.net
Subject: Re: [Elecraft] Parting shot


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
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:Elecraft at mailman.qth.net

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html