Re: So what is API documentation anyway?

[Peter Neilson <neilson -at- windstream -dot- net>]

APIs are subroutine calls that are designed as a programming interface 
that an application program will use for communicating with the 
operating system, or with another program. I've written about them.

You've gotta have done some computer programming to understand how APIs 
have to be documented. Once you've done programming where the existing 
descriptions of calls to the operating system or to another application 
or a library were badly done or broken, you'll have an understanding of 
difficulties such as the following, and perhaps know how to spot them:

  - Missing description of parameters.
  - Wrong, ambiguous or missing type for parameter.
  - Permissible range of parameter values not specified.
  - Typographical error in name or calling sequence of API call.
  - API call omitted from list.
  - Needed API call missing because it was never designed at all.
  - Deprecated call included in list.
  - Call's return value not set, or incorrectly set.
  - Call-by methods (by name, by reference, by value, or Lisp-like) 
require mention but are not specified.
  - Side effects of call incorrectly given or not specified at all.
  - Actual purpose of call not properly explained.
  - There are six different descriptions of how the call works:
       = What the developer said to you.
       = What the developer wrote in his notes.
       = What the functional spec or design spec asks for.
       = What the tech writer thinks it's supposed to do.
       = What the code says it does.
       = What the application programmer really wanted.
       None of them is correct.
  - Missing (but needed) examples of use of an API.
  - Sequences of use of various API calls to perform an overall purpose.
  - Description of environment within which to work.

There are others.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.