/customers/iconara.net/iconara.net/httpd.www/blog/wp-content/plugins/wp-super-cache/wp-cache-phase1.php Iconara » API documentation is not documentation

API documentation is not documentation

I have started to play with ActionScript 3 and the command line mxmlc compiler (which is free, horray). Adobe has posted some interesting libraries on labs which I’m interested in trying out. When you download the frameworks you get three things, the compiled swc, the source and the documentation.

Except you don’t.

You don’t get any documentation. What you get is the generated API “documentation”, which is like throwing a gadget without any visible clues as to how it’s operated in someones face and say “you figure it out”.

Its such a waste of good code! Some of the frameworks have tens of classes in them, how do I know which ones to use? I’ll have too look through everything just to get an idea of what it can do.

A simple “this is the bare minimum of code you need to do X” would suffice, from there I can experiment my way to understanding the whole framework.

If you are going to distribute a framework or library, at least include an example of the most common usage of the framework. If you can’t bother doing that, don’t bother releasing it.

Luckily there seems to be (more or less) third-party guides to some of the frameworks, so I’ll get by. It still makes me disapointed, however.

2 Responses to “API documentation is not documentation”

  1. Iconara » Architectural Atrocities, part X: Cairngorm’s Model Locator pattern Says:

    [...] But I hear you protest, “there is lots of documentation! there is extensive API documentation!”. Well, if you’ve read this blog for a while you should know what I think about API documentation. [...]

  2. Jon Says:

    He’s right. Not even an example app to show the basics. Pretty lame if you ask me.

Leave a Reply