Re: Specialized formatting for APIs

[Chris Knight <knight -at- ADA -dot- COM>]

John Posada (work account) wrote:
>
> Hey, guys...
>
> I'm involved in a project that involved documenting a hundred or so
> Application Program Interfaces (APIs).
>
> I'd like opinions on what type of formatting you've applied or what you
> would have done differently when you've creating the same type of
> specialized information and if anyone knows of either web links or books
> on this particular subject.
>
> I've gotten it down to 6 sections for each one.  Each API may not
> include all the sections (i.e., there may not be any notes for a
> particular entry:
>
> Syntax: an example might be fsInit(HTASK hTask ,LPCSTR pszId, DWORD
> dwFlags)
> Description:
> Parameters:
> Code Example:
> Return:
> Note:
>
> All of the hundred except to maybe 5-6 fit on page page and I'm starting
> a new page with each one.
> I place the code example inside a frame using Arial to avoid alignment
> adjustment. problems
>
> Aside from the preferences that everyone may have that don't affect
> meaning, are there any hints or tricks that anyone has used to make an
> unusually effective document from the programmer's standpoint.
>
> I'd even settle for any publications that documented this type of
> information in a way that you were impressed with that I could use for
> hints.

I've done a lot of these and it sounds to me that you've got it right.
I would make the writing as terse as possible. Don't be afraid of using
non-sentences in your explanations.

Two suggestions: I would say "Returns" rather than "Return", and I would
look for structs (data structures) to document as well as functions.
Typically one or more API function writes to a data structure, and one
or more function reads from the structure. I've found that many API
guides don't discuss these structs as such (the info may be in one of
the functions' description) and developers using the API really
appreciate the care taken to document them.

--
Chris Knight
Consultant, Technical Communication Architect
Vancouver BC, Canada
(currently at Applied Digital Access,
e-mail: knight -at- bcg -dot- ada -dot- com)
Opinions expressed are my own, not ADA's

Posts: mailto:techwr-l -at- listserv -dot- okstate -dot- edu
Commands: mailto:listserv -at- listserv -dot- okstate -dot- edu (e.g. SIGNOFF TECHWR-L)
Archives: http://listserv.okstate.edu/archives/techwr-l.html,
	http://www.documentation.com/, or http://www.dejanews.com/
Subjects: JOB:, QUESTION:, SUMMARY:, ANNOUNCE:, or none of these.