Re: Learning C code... (fwd) *Long*

[Diane Peters <dj -at- IBAPAH -dot- RAXCO -dot- COM>]

The following was my husband's response to my "Learning C code" mail, he
is a very experienced and knowledgable Unix programmer, who happens to
have a keen interest in technical documentation.  He should, he reads tons
of the stuff.  Please forgive us any spousal prejudices that you may find
in this message.  Wes' comments are quite informative.

Forwarded message:
> From wes -at- intele -dot- net Fri Nov 10 17:15:39 1995

> Well stated!  People who refuse to upgrade their skills are always
> so suprised when they just get passed by...  (Ask those legions of
> VAX/VMS programmers out there dying on the vine.  ;^)

> > After reading several responses that reveal such resistance to learning
> > C code (or any programming language), I feel compelled to share the
> > following.
> >
> > Many technical writing jobs require this skill for good reason.  Have
> > any of you ever heard of an API?  I'm not sure of the translation of
> > this acronym, but I believe it stands for Application Programming
> > Interface.  The "interface" in this case is the document, which is a
> > result of the efforts of a technical writer, possessing skills in both
> > writing and reading code.

> Actually, the API is the publicly-accessable part of a program;
> the part "exposed" to users.  For instance, if I'm writing a library
> that maintains lists of objects, I would probably have routines to
> create a new list, add an item to a list, remove an item from a
> list, and locate an item in a list.  For other programmers to be
> able to use these functions, they have to know that they exist,
> and how to call them from their own programs.  *This* is where the
> documentation is required, because we're not going to let the
> customers actually see the code, but they have to know enough to
> use it.


> > Most APIs are for internal use only, and the "user" are programmers,
> > who rely on this documentation to understand existing programs, train
> > new programers, provide a programming standard, and for a history of
> > what has been done before.  Other users of APIs include:  QA departments
> > to write testing scripts and technical support organizations for an
> > indept understanding of products they must support.

> Most internal APIs are never really documented, for the simple
> reason that the users can always look at the source code to figure
> out what it does.  It's not a good solution, but it certainly is
> widely accepted.  On the other hand, we have companies whose products
> address most, but not all, of a customers need in a certain area.
> Many of these companies are now receiving *demands* from customers
> that they make an API into their products available so the customers
> can complete the 5% of the requirements not addressed by the vendor.

> Then, of course, you have all of the companies that make APIs for
> a living, which include both function library vendors, like XVT
> and Visix, and system software vendors like Novell, Microsoft, Sun,
> Digital, etc.  They have an *obvious* need for API documentation;
> an operating system is really nothing but a bunch of APIs.

> > There are entire technical writing departments of several technical
> > companies, that I know of, whose only function is to read programming
> > code of software products and produce API documents.
> >
> > So, there is a very practical reason for a technical writer to gain
> > comprehension of programming languages (the most common of which is now
> > C and C++).  As for a resistance to learning a new skill, I am somewhat
> > dumb-founded.  Knowledge and experience are two things no one (and
> > nothing) can take from you.  Besides, you never know what doors this
> > could open for you in the future.  Also, there is a certain amount of
> > independence that comes with every new skill.
> >
> > I must agree, in closing, that if your employer expects you to actually
> > program products that it intends to sell, then they are asking you to
> > do someone else's job.  To learn to program for products or equipment
> > that you use to do your own (writing) job, I really think the request
> > is reasonable.  That's all I have to say on the subject.

> This would be *almost* as stupid as asking the programmers to write the
> documentation.  Present company excepted, of course.  ;^)  (I mean that
> both ways, too.)

> > [Phew! I thought she'd never shut up! ;) ]

> Nah, she runs out of steam eventually...

> --
>    Wes Peters | Yes I am a pirate, two hundred years too late
>     Softweyr  | The cannons don't thunder, there's nothing to plunder
>    Consulting | I'm an over forty victim of fate...
>  wes -at- intele -dot- net       |                                       Jimmy Buffet