Re: SDK/API Documentation

Subject: Re: SDK/API Documentation
From: Doug Nickerson <Doug_Nickerson -at- ONSETCOMP -dot- COM>
Date: Thu, 22 Oct 1998 09:40:24 -0400

Hi John,

On this documenting an API issue I have a bit of
a harangue.


My programming background causes me to suggest:
what the UNIX programmer told you, although not an original
misconception, is serious crap.

I haven't got a clear idea of your product, but let's summarize it as
followins:

1. Documentation of how to use a Software Development Kit -- how to
use the varios functions, linkers, compilers, support software, libraries,
to best develop
whatever it is the customer wants to develop.

2. Documentation of an API -- the collections of functions (called message
or
member functions in O-0 terminology) that a programmer (presumably using
the
SDK) can call and link in to create a program.


Comments
A. It's absolutely normal to expect some documentation for an API.
Microsoft, Borland and others have gone to lengths (lesser lengths lately)
to provide descriptions of
what an API (Win32 for example) does, how it behaves, what functions
should
return and what they mean. The Win32 API is immense--it can't be used
without documentation.


B. Object-oriented programming, in many ways, is more complex (rather than
less complex) than other types of programming, such as procedural
programming.
It's very common to obtain (at least) a heirarchy diagram of the structure
of
how classes in the system are related to one another. And, this is not
enough by itself.
Also, header files documenting the data and functions (messages)
available
with this product could be released. You could go find out (IMHO). After
this
you need some documetation to tell what classes in the system do, what
the messages do, their return values, & so on.

C. The use of object - oriented programming in no way absolves
programmers of the responsibility of commenting their code. Commenting is
taught in school today, and lack of commenting, is regarded in
modern-thinking
circles as a sign of, at least, laziness .

D. One of the consistent worries in using the programming systems supplied
by
Microsoft and others has been lack of adequate documentation.

[I'm primarily a programmer, have written what
you could call APIs (an overworked term, and I defer
to dmbrown's message on term definitions)--most of my writing has been for
programming magazines in the O-o area, and a book on Java.]

My sympathies,


Doug Nickerson
doug_nickerson -at- onsetcomp -dot- com

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: Re: Learning from others
Next by Author: Re: FWD: Consultant challenges/editing
Previous by Thread: Re: SDK/API documentation
Next by Thread: Eliminating .txt file hard returns -Reply 2


What this post helpful? Share it with friends and colleagues:


Sponsored Ads