Date: 15 Mar 1993 08:42:36 -0500
From: "Mark H. Wood" <IMHW400 AT INDYVAX DOT IUPUI DOT EDU>
Subject: Re:  thanks and GNUish advocacy
To: DJGPP AT SUN DOT SOE DOT CLARKSON DOT EDU
Organization: Indiana University - Purdue University at Indianapolis

>From: jshumate AT wrdis01 DOT robins DOT af DOT mil ( Shumate Jason;WR-ALC/DSMDC)
>Subject: RE: thanks and GNUish advocacy
>
>
>>        is J. Alan Etheridge 
>> >      is me
>
>> 
>> > is that IMHO debug32 is really poorly documented.  It would probably be
>> > more useful to many of us if it had a decent page or two of examples 
>> > showing how to use it.  I have had all kinds of trouble using it without
>> > any examples to follow.
>> 
>> void personal_opinion() {
>> 
>> Hurm.... at the place where I work, if anyone says, "It would be
>> really nice if [...] were better documented", our boss says, "OK,
>> write a document on it!" ... Are you volunteering? I hope so. If not,
>> well, those of us who write this stuff also have day jobs and many
>> have families - it's a miracle we can crank the code out. :-)
>> 
>> }
>> 
>I'm sorry I seem to have greatly offended you.  If you would take the time
>to read what I said, you would have understood that since I have trouble
>using debug32, I am hardly qualified to write documentation on it.  I do
>have the time to write said documentation, despite also having a day job.
>I would be gald to do so I if knew how to use the #$%@# thing.

Once upon a time, the TOPS-20 OS came with an unsupported goodie called the
Programmable Command Language.  When I say "unsupported" I mean we got only
partial sources and *zero* documentation.  PCL seems quaint today, but it was
miles ahead of anything we'd had before back then, so I wanted to know how to
use it.

So, with the help of a very good disassembler, I turned the object modules back
into assembly source, then went through them several times figuring out the
more understandable bits and writing comments for every line that I could
understand.  I stopped when I ran out of things that I didn't understand. 
(BTW, the original source was *not* assembly but BLISS-10, a language known for
a very clever code generator and syntax even more bizarre than C can be.  I
discovered this by inspecting the code.)  Then I read the comments and wrote a
manual for PCL.  Then I wrote some PCL code and tested it, and rewrote some of
the manual.  (By this point I suppose I didn't *need* the manual anymore,
except as a goad to make me finish the work.)

I don't write this to shame you or tick you off, but to encourage you, and to
point out what anyone can do if he cares enough.  When I started on PCL I was
wholly unqualified to write documentation for it; I became a minor PCL expert,
the hard way, in order to write it.  This is the same thing that any tech
writer or programmer does, really.

Writing a good DEBUG32 manual would indeed be easier for someone who thoroughly
understands it already.  But I submit that those who care the most about the
creation of such a document are the ones who *don't* understand it.  (I don't
understand it myself, but I haven't yet used it enough to need a manual, so I'm
not going to write that manual for you either.  Not right now, anyway.)

(Okay, I had another reason to write this note:  I'm proud of my achievement
and have been dying for a chance to tell the story!  Thank you for the
opportunity to relive one of the most rewarding experiences of my career.)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mark H. Wood, Lead Systems Programmer    +1 317 274 0749   [@disclaimer@]
Internet:  IMHW400 AT INDYVAX DOT IUPUI DOT EDU     BITNET:  IMHW400 AT INDYVAX