Robert Lauriston wrote:
> What language is the API written in?
Can't comment on the original question posed, but, FWIW, our API's are written
in C++ for some, web services (XML/SOAP) for others, and, more recently, REST
for some new web interfaces.
For our API documents, in the past 13 to 14 years, I wrote the content in
FrameMaker (version 6.0 onwards). Recently, I have switched to LaTeX for new
documents and specifications, but have not updated any of the older API
documents into LaTeX yet.
In terms of general advice for API documentation, I'd say that there is one
simple best practice to follow well:
Accuracy of information and content is critical.
So, for example, using automated document generation from an IDE to "feed" into
the writing tool, is extremely useful. Of course, the output from such tools is
not the most easily "read", so editing is essential. :)
In API's in XML/SOAP, for the documentation for our customers, I use the
*actual* WSDL files to create input into FrameMaker (edited appropriately, of
course - there is no need to show the content of the WSDL in a trivial way).
This ensures accuracy - if the documentation ends up being wrong, well, then
the API and code are also wrong in the same way at least! :)
For C++ based APIs, I use the include files (the .h files) as input for my
content. Again, this ensures consistency and accuracy. In FrameMaker, I also
use the .h files to create the FrameMaker variable files (since I use and love
BookVars!) to get accuracy.
Style, content, and degree/amount of explanation for the API documentation is
based on a mix of API documents that I have seen from Microsoft, Sun
(pre-Oracle) and Google. I don't know if I would call this best practice per
se, of course. :)
Finally, a good review process, and feedback from your engineers and the
customers (the ultimate users of that documentation) is also a Good Thing.
Z
