TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
OK, gang. I suspect that a pretty small subset of us deals in
documenting Application Programming Interfaces.
[For those who have been following TECHWR-L for some while, this
IS the same set of documents I set about single-sourcing, using
FrameMaker conditional text, text insets, and variables. It worked
pretty well, but does require discipline.]
I'm documenting APIs for our product, and there are three flavors
of API: one for C, one for COM, and one for Java. Each flavor
has its own manual, but the introduction chapter and the installation
chapter is basically duplicated across all the manuals, and
occasionally I need to make statements about the set of all three.
But C is a language, Java is a language, and COM is a ..., well, it's
the Component Object Model.
Much of the actual invocation of functions/methods through the
COM model is done from programs written in Visual Basic, but it is not
limited to VB. COM is not a protocol, like TCP/IP. It is a defacto
standard, not an NIST standard. It is like CORBA (Common Request Broker
Architecture) -- an agreed-upon way of doing things.
I'd like a "handle" I can use to refer to this set of three
"ways to access the system".
In the case of the C API, any language that can create calls that are
compatible with the C language calling mechanism can call functions of
the API. The description of the calls by which the API is documented
are C call statement prototypes. Each call sends a set of arguments to
a server and receives a response back that is either a complex data
structure or a diagnostic error structure. This version of the API
is not object oriented.
I can't (accurately) talk about the three "language interfaces"
because COM is not a language. I can't talk about the "three
architectures", because nobody refers to the C calling mechanism
as an "architecture". Let's not even THINK about calling it
the "three protocols". Most readers see "protocol" and think
The Java API is object oriented. Essentially for each call
in the C API, there is a class in the Java API that is instantiated
and populated to create an argument object and then the program
makes a call to pass that to the server, receiving a complex
data structure or a diagnostic error structure. The description
of the classes and their methods is very much like a JavaDoc of
The COM API is not now object oriented, but might become so.
Its description is in an IDL (Interface Definition Language)
form, showing which parameters are input, which are output,
which are both. Its behavior now is much like that described for
C, but is likely to change to be more like that discussed for
the Java API.
Has any of you ever had to address this sort of a problem, where
there are multiple APIs that provide entree to a system/product
from a family of different protocols/mechanisms/language-milieus?
--Thanks for any guidance you can offer,
Guy K. Haas gkhaas -at- usa -dot- net or ghaas -at- selectica -dot- com
Software Exegete in Silicon Valley
Your web site localized into 32 languages? Maybe not now, but sooner than
you think. Download ForeignExchange's FREE paper, "3 steps to successful
translation management" at http://www.fxtrans.com/3steps.html?tw.
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.