The Glass is Too Big - Home

I've been messing with the Metaweblog API and Javascript again, to hook into Outlook for writing up notes and posting to this and my other sites. I've been sorely disappointed in the documentation for this API.

What gets called "documentation" varies quite a bit. There are usually several different types:

• Object model documentation. This is a blow by blow explanation of every method and property in the code. When it's really good, it covers what the bit you're looking at connects to, as well as sample code to show how to use that method or property.
  
  
• Tutorials. These show you how to accomplish something specific using a set of tools.
  
  
• Descriptive articles. These are often written to give an overview of a topic. They aren't aimed at a particular task or at being exhaustive. These are great when, say, someone wants to know how PHP is different from Perl. You can cover the highlights and leave them to the object model docs, etc. when they need better details.
  
  

Unfortunately, the document that gets pointed to as the "API documentation" for the Metaweblog API is in the last category. It's a fine article, but as API documentation, it's really quite sad. I'm used to the detail that the PHP documentation has. When I'm busy implementing the spec, I need to know all of the details. I want to see examples.

For instance, when it tells me to pass in a "struct" without telling me the exact structure of that struct, it's a frustrating experience.

So, when looking for better docs, I noticed that the new MSN Spaces implementation happened to come with MSDN-style documentation and that Microsoft made a great move in choosing an open API (the same one I'm working with), but even better, they improved the documentation as they did it. I'm not generally a fan of Microsoft, but I'm also a pragmatist and tech agnostic and aim to use what works above any religious affiliation.

So, if you would like to understand the API or if you are Dave Winer and you're thinking of writing docs that will help people spread the standard you've come up with, go read theirs.

© 2003- 2010 J Wynia. Very Few Rights Reserved.