[PLUG-TALK] [PLUG] On teaching geeks to write

[Keith Lofstrom]

I am moving this to plug talk - it is a valuable 
discussion, but only tangentially related to linux.

On Tue, Dec 04, 2012 at 09:40:22PM -0600, Richard Owlett wrote:
> I need an example more current than the hole I dug myself 
> into some 40+ tears ago when I, as an engineering co-op, 
> wrote a production test procedure which depended more on my 
> experience with a color TV with a CTC-2 chassis than I 
> realized. Anybody here old enough to recognize my error when 
> I said to center a spot on a CRT by rotating a magnet on its 
> neck.???
> 
> i hope there is someone out there doing a ROFL

No - all procedures involve knowledge and context, of both
the reader and the writer.  I can write a one paragraph
procedure that functions admirably as a reminder to an
experienced technician who knows all the steps but forgets
one or two.  I can write a book length description that
won't help a person with zero context - or who is
illiterate, learning resistant, or frightened.   All
training documents should be tested on multiple pupils.
Let them read it, and watch what they do.  Ask them to
describe what they are doing, don't interrupt, and take
notes.  Often, the result should be an improved procedure
rather than a more accurate description of an inadequate
procedure.

For example: My guess is that Free Geek has been a very
good discoverer and documenter of procedures that worked
for volunteers with little background and experience. 
Another guess, based on the evolution of all technical
organizations, is that they are slowly getting worse
at it, with an attitude of "what is wrong with you
idiots" gradually replacing the "lets learn together"
attitude that characterizes young organizations groping
their way towards something that works.  Sooner or
later, they will get old, and some younger organization,
full of energy and ignorance, will replace them.  They
are still way cool, though!

When you teach the same thing over and over again, you
get stale, and your pupils are well aware of that.  So
it is often better to have engineer co-ops and interns
do the teaching;  the mistakes they make teach them to
understand the mistakes that their pupils make.

Keith

-- 
Keith Lofstrom          keithl at keithl.com         Voice (503)-520-1993