Re: API style guides?

[Sara Schertz <SSchertz -at- INTERFACESOFTWARE -dot- COM>]

I worked on an online API reference for our product. I didn't find any
standard styles out there -- instead, I worked with a programmer to come
up with some standards we thought would work. We used the function
references for Visual Basic and C++ as a guide, and sort of mixed and
matched the styles together until we came up with something we both
liked.

The key was getting programmer input. They had a pretty good idea of
what they DIDN'T like in the references they currently use, so we were
able to avoid some problems. For example, every programmer I interviewed
agreed that there is no need for a 500 page function reference -- they
would rather have it online with searching available. A function
reference is not something you read beginning to end -- you look it up
and then move on. Ideal for online.

Another thing to think about -- the syntax for describing the functions.
Our functions are documented in "C" syntax -- meaning, the words we use
for data types are those used to describe data types in the C language.
For example, in C, a "pointer to a string" is referred to as a "LPSTR".
In Visual Basic, this is declared as "ByVal as String". When using the
reference, a Visual Basic programmer has to translate those terms into
VB. (my knowledge on this point is shaky -- this decision was made by
the programmer who wrote the API itself and provided the design
documentation -- however, this seems to be fairly standard. For
instance, the Visual Basic programmer's guide specifically explains how
to do this translation when programming with an API.)

Also, consistency is very important. Every topic in our reference has
the exact same layout. The online guide was STRICTLY a function
reference -- it did not tell you how to program, but instead simply gave
the details about each and every function in the API.

We did not include significant code examples in the reference. Any such
examples WOULD (probably) have to be programming language specific.
Instead, one of our developers created a set of small sample programs
(in Visual Basic) that highlight various functions.

I am now currently finishing up a Developer's Guide for the same API,
which DOES tell you how to program -- we found that the reference alone
is just not enough. In this case, we have many code examples. We picked
one language that we think most of our customers will use (again, Visual
Basic) for the examples.

Finally, I am not a programmer either (although I did do some
programming in college), and I was able to write a book telling
programmers how to program!! so don't let anyone tell you that you can't
do it. I found it to be great fun and a nice change from some of my
other projects. Very challenging, though.

If you have any other questions or want to know more about the styles we
used, feel free to e-mail me directly.

Sara Schertz
Interface Software, Inc.
sschertz -at- interfacesoftware -dot- com


> -----Original Message-----
> From: Lani Hardage [mailto:lhardage -at- RMTECH -dot- COM]
> Sent: Thursday, May 21, 1998 3:40 PM
> To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: API style guides?
>
>
> Hi, Techwhrlrs, I've searched the archives but not found
> anything about
> styles for documenting APIs. I have one from a programmer (C++) that
> doesn't seem to follow any conventions I've found in looking at APIs
> such as HTMLHelp, Java classes, and MAPI32 for Visual Basic. Can you
> point me to some standard format(s) you've found, or is there no real
> standard? The above examples were not all alike.
>
> For starters, it looks like you have a list of functions, with name,
> description, parameters, values, returns, and then perhaps related
> functions/methods and a code sample. Is some of this dependent on
> programming language?
>
> Please don't tell me not to do it because I'm not a programmer --I
> really don't have a choice, and besides I want to learn.
>
> TIA,
> Lani Hardage
> Risk Management Technologies
> Berkeley, CA
>
> &^&^&^&^&^~~~
> Send commands to listserv -at- listserv -dot- okstate -dot- edu (e.g., SIGNOFF
> TECHWR-L)
> Find TECHWR-L-related books at
http://www.raycomm.com/techwhirl/books.htm