Writing APi documents - best practice

[Syed Zaeem Hosain (Syed.Hosain@aeris.net)]

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