Wednesday, July 16, 2008

Google API Documentation

One of my annoyances of dealing with many Open Source projects is the lack of documentation. nHibernate is a prime example - it's a fantastic technology with minimal documentation. The only book on the subject is a year late (and counting.)

I no longer find it entertaining to beat my head against a wall for days (or weeks) trying to figure something out that should have been documented in the first place. I don't mind paying for answers anymore. $200 is a small price to pay to get an answer that saves me a day of work.

I was therefore terribly disappointed by the tremendously poor quality of the documentation for the .Net library for the Google API. In the best tradition of F/OSS, the documentation for it is desperately lacking. Most functions have little more than a terse one-liner description, with no additional remarks. If it weren't for the fact that source code was included, trying to determine how to use the API might well be impossible.

A typical example is Captcha handling. The Google API will sometimes request the user to solve a Captcha to make sure that a human is really present. The problem is that there is no C# source code to demonstrate the correct response. Captcha is not handled by the sample code or the unit tests. It's mentioned in the newsgroups, but none of the responses actually contain code that works.

A more pathological example is documenation on the Contacts namespace. Try clicking on GroupMembershipCollection. No dice - broken link. Try looking at the code in the Samples directory. No help there, there's no sample code for contacts. Try looking at the Java library. Nope, it works differently from the .Net library (That's not a dig in this case. Both libraries are crafted appropriately for the style of each language.)

There's also no one you can call if you have a problem, even if you are willing to pay for the answer. Say what you will about Microsoft, but when they support something, they mean it. Monitored newsgroups, books, tech support, consultants, 3rd party training - you name it, the resources go on and on.

Google has a lot to learn about providing services to the enterprise market.

1 comment:

  1. Good article. I agree about Microsoft support.