Re: So what is API documentation anyway?

Subject: Re: So what is API documentation anyway?
From: Peter Neilson <neilson -at- windstream -dot- net>
To: "A.H." <isaac840 -at- yahoo -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sun, 25 Mar 2007 23:57:23 -0400

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 &amp; 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 &amp; 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.


Follow-Ups:

References:
So what is API documentation anyway?: From: A.H.

Previous by Author: Re: System Requirements
Next by Author: Re: Word Appendix Numbering
Previous by Thread: Re: So what is API documentation anyway?
Next by Thread: RE: So what is API documentation anyway?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads