Just the other day at work I was tasked with exploring various widget api's to see if there's potential in integrating our telephony product with these various web 2.0 sites. I've spent the last few days looking over the basics of the iGoogle and Facebook api's, and there was a stark difference.
I started with iGoogle. I googled for “iGoogle api” and the first hit was this link to the Google Gadgets api documentation. Right there on the front page it says “Write a gadget”. I click Developer Guide, then “Hello, World”, and there's some gadget code right in front of me. One search and two clicks is all it took to get a basic idea of how Google Gadgets work. Further reading of that page, and the next step in the documentation, “Writing Your Own Gadgets”, gave me all the information I needed to know. Total time: about an hour.
Next was Facebook. Googling leads me to the Facebook developers portal. “Getting started” looks like a good place to start. All it tells me is to install the Facebook developer application. I did that, and tried to start a new application, but it asked me for things that I don't know anything about. So, back to the documentation. Hmm, nothing else on this page. I'll click “Documentation” up top. I read around here for a while, and there was a lot of specific information but not general type stuff like I'm looking for. Down at the bottom I eventually see a link called Anatomy of a Facebook Application. This has got to be what I'm looking for. Nope! It describes all the ways a user interacts with your application, but no anatomy at all. I'm getting frustrated at this point; I've read all kinds of details about the Facebook api and what the application looks like to the user, but still nothing about how I go about writing one. (Notice, I don't think they've even told me it's written in php yet!) Finally, I see Guide to Creating an Application. After hours of looking, I finally find what I want. The guide is pretty good, but the example application doesn't work. I can't look at the finished product while I read what's going on under the hood. Total time: A day or so, and still counting.
It's pretty clear to me that iGoogle has people behind it who know what they're doing and Facebook needs to get their act together. Their api has been out for several months, they need to get some good documentation written and better organized so developers can more easily figure out how Facebook applications work. There's no excuse for it really, these applications that confused people aren't writing could be adding considerable value to Facebook. For now though, I'm ignoring the silly walled garden and sticking to iGoogle.