Contents 
 Index 
 "TPT User's Guide" 
 < Previous 
 Next > 

API Documentation Rant

The beauty of application programming interfaces (APIs) is that once they are defined, they aren’t supposed to change. This may give the mistaken impression that its documentation can be written with a one-time push and minimal effort in subsequent releases.

Traditional software documentation projects may require many screen shots of the application whose content the software engineer can re-arrange, rename, and re-locate at any point in time in any release. The documentation needs to keep up in order to be accurate.

API documentation projects, on the other hand, explain “what” the API needs and does, but not necessarily the details on “how” it is accomplished. The “what” isn’t really supposed to change or be deleted, otherwise you will break your customer’s code which is programmed to the API. The internals of the software below the “what” could completely be gutted and it may only have minor effects to the documentation. Subsequent releases of the documentation mostly only need to be concerned about what was added to the API.

The API code can go through many massive overhauls in the versions leading up to the code freeze of the first release. You can expect:

• The naming of API items to change as the software engineers get in step with legacy code, new conventions, and each other.

• The naming, number, type, and ordering of arguments to API items to change radically as they experiment with what’s needed and works and as they conform to others on the project.

The churn in the API software leading up to the release can be even more drastic than the top-level GUI changes which require new screen shots in traditional software documentation projects. In fact, code freeze and beta release to a customer is when promises from software engineering of no more changes affecting the documentation can be believed.

Unfortunately, this is pretty late in the release cycle to expect accurate, complete, and quality documentation, at least for release one.

... Unless the API documentation is revisited from a holistic point of view overlooking the whole organization.



 "TPT User's Guide" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-hug-02