I, and several people I know, have been in this situation before. Facebook seems to have very little commitment to backwards-compatibility and comprehensive documentation.
On a more general note, I’d strongly recommend against building your entire business around a single platform.
> strongly recommend against building your entire business around a single platform
I see this statement a lot and I never understand it. If you're Zynga, should you build Farmville for OpenSocial and as an independent site too? The cost of doing this seems prohibitive.
Most businesses built on Facebook can be taken elsewhere if the cost of the Facebook platform starts to outweigh the benefits. Even Farmville can be ran independently, but consider how many users they'd lose in the transition and afterwards.
Most smaller operations are going to be pretty much writing software for a primary target platform.
It is nice that there are technologies like cross-platform application framework or CSS, that let you create code for your target platform that you might just be able to port to another platform at a later date. But that doesn't take away from the fact that you're likely going to be betting on a given platform at a given time.
Perhaps what you want to say is "don't develop for a platform that will stand in the way of you porting at a later date" - indeed, all the walled-garden stuff seems to have this lock-in quality and would make sense to avoid - if you have a choice.
To clarify this point: the Facebook platform is provided gratis, but there are no contractual obligations preventing them from yanking, changing or breaking the service. As a business, you must ask yourself how easily you could adapt if they were to do so. Is that a risk you are willing to take?
tl;dr: Don’t put all your eggs in one basket, especially if said basket has a history of breaking.
I recently ported my app back to the old Javascript API; I wish I could say that it was for the superior older documentation, but it was actually because the new API randomly stopped returning my calls from time to time.
All of the big moneymakers' apps are built on the older stuff, so I figure when it breaks, it gets a bit more love.
The documentation is still shoddy, the Bing-powered documentation search is abysmal, and when things don't work I don't understand why. I'd have happily paid a few hundred dollars to be part of the developer program and have a contact over there, but they killed that. Ah well.
Part of their new 'commitment' to developers (Facebook apparently created an internal Games team several months ago) is a stated paradigm shift towards more and better documentation, but it seems so at odds with the way things are currently done that I'm pretty skeptical.
It does seem as if someone over there is aware that the current situation is pretty awful, at least enough to say "we're working on it".
This is a throwaway account. I'm a full-time developer for a huge company that uses Facebook as it's platform.
There still is a preferred developer program for the bigger companies out there but it doesn't really offer much of anything. Go back a year though and it was a big benefit.
This is Bret Taylor's Graph API - the concept simplified the API a lot, and companies like Freebase copied it for their own data. Too bad it is not working...
The way Facebook's Graph API is structured can be applied to other datasets containing interconnected objects. It's like a REST service serving JSON, with a specific way to construct the URLs. I like it a lot. Here is a blog post explaining the Freebase implementation:
Many of Ryan's complaints apply both to the graph API and to the older APIs, although one of them is that the graph API isn't maintained properly (which has been the case since the beginning).
I'm glad I'm not the only one that feels this way about their documentation. I don't make Facebook apps all the time. I've made a couple. Each time a client has me make one I have to spend hours trying to gather info about whether a requirement is possible because the docs suck.
Their API woes lead to problems with other components they offer. Their original iphone sdk component was one of the more polished freely available objective c components out there. Their updated version using that relies on the updated API's is a step backwards in functionality, ease of use and documentation.
that's pretty much the tldr of the post. I've no idea why it's on the frontpage. I thought it was going to be some philosophical objection to the walled-garden approach, or some experience with facebook being anti-open web, or the way fb apps teach users bad habits or at least something of substance. but really it was just a rambling rant.
All of those would be interesting posts, but I don't really have a problem with them. I do have a problem with the way Facebook treats their developers, so that's what I wrote about. I'm sure the post could have been better, and I'd enjoy any specific suggestions you might have. Thanks!
I think they do this on purpose - rapidly changing apis, and having poor or overly verbose documentation is a way to weed out all but the largest development companies, thereby reducing support costs, and allowing partnerships with the big companies that survive. It's right from microsoft's playbook.
Instant personalisation helps to give this impression, that they are working very closely with bigger players who can get regular contact with those at Facebook to know the API inside out and get notified of changes as soon as they happen.
You think "rapidly changing apis" is "right from microsoft's playbook"? Microsoft has been known to abandon a platform (VB6 being the prime example), but they have also put tremendous effort into preserving compatibility in their APIs. So while they may have introduced new APIs over time, they've also shouldered the massive burden of keeping the old way working for many years. I would even say they realised this was a vital component in maintaining their dominance: the sheer number of applications that work on Windows.
This is a throwaway account. I'm a full-time developer for a huge company that uses Facebook as it's platform.
Ww get next to nothing useful from facebook these days. Sure, we have a dedicated internal contact, but it isn't very beneficial. We hear news maybe a week before it's released to the general public, but there is no feedback from them on critical regressions that affect our business. Facebook is pretty much a black hole when it comes to communication.
It seems like a cultural issue. We were at an event on Tuesday where they let us know about a host of API changes relating to apps specifically, but when I got back and emailed asking for some documentation (even anything internal), all I got was a "we'll get back to you."
Ironically (or maybe not), part of the presentation was a slide featuring a workgroup with a "Done is better than perfect" poster. Well, yeah, but when you're running a platform service...
He's right on the money. The documentation is horrible. The 1 app I wrote that used the Facebook APIs convinced me never to do so again. Even the simplest things required hours and hours of effort, mostly by trial and error, just to figure out the important details that the documentation left out.
I like how Twitter has versioned their API, and I wish Facebook would do something similar. With 500+ developers and deep knowledge of backend changes, they should be able to handle the minor discrepancies instead of off loading that burden to platform developers.
The Twitter API is excellent in comparison, I guess in a way the newer Facebook API drew a lot of inspiration from it. Problem is it was rushed out and judging by the article and comments left here not much has happened documentation wise in the last 3 months or more since I last touched it.
You can do everything through the API that you can on twitter.com. In fact the new twitter.com site uses the API! One more thing, their API does what it says in the docs... when twitter is up ;-)
I found at times that I got more info from the depreciated wiki than any form of new documentation they had up, and my use case was pretty damn simple, just implementing a half decent usage of facebook connect which runs with SSL and plays nice with a modified wordpress user system.
I found myself at times resorting the trawling through js source to find how I could use certain button images that were very simple in the old version.
I feel your frustration and am glad I don't really have to do much in the facebook space at the moment.
I think the issue Ryan mentioned with FB is a general issue these past several years with more than just FB's API and documentation. Everyone seems to be more sloppy these days. People call their processes agile, throw in a task manager, throw tasks into it willy nilly, and call that process.
Hiring a tech writer and sending your lead dev to scrum school won't help either. You need to value good work at work. If you're too busy worrying about how to skim by with less money or worried about losing your employees, you're too distracted. Work with fewer people, get less done, but make sure you do it right! Why do people need a primer on this? It is just common sense.
Their iPhone Facebook Connect documentation is beyond atrocious. What little there is was written by someone who, besides not being a non-native English speaker, also does not care about getting things right.
Several people have mentioned how bad the documentation is, but nobody has provided examples. In case anyone from Facebook (or "facebook" as it's sometimes called in the docs) reads this and cares, I'm putting some examples from the docs below.
The problem with having mistakes in the docs, is that as the reader notices more and more mistakes, they begin to have less and less confidence in everything that is written there. Once the documentation is suspect, every word in it is suspect.
Here's an example of a sentence lifted from the docs: "i whose fields and values can be inspected and accessed."
Yes, that was the entire sentence, if you can call it that.
How about: "Application can implement these interface to handle them."
Seems like a small error, but a more important message is given to the reader: You cannot trust this document.
Just to preempt an obvious reaction, yes, you shouldn't trust any document, but there are levels of trust, and this kind of grammar makes the trust fall quickly to a very low level.
Another one: "The FBSessionDelegate is a callback interface that your application should implement: it's methods will be invoked when the application successful login or logout."
Same message there. You can't trust this.
Then there are the code examples. Here's their example of how to use something the docs call a stream.publish flow:
Ignoring the bizarre inconsistent use of spaces after colons, this example gives no clue about what else should be in the params object in order to make a publishable post. I could look it up on the Facebook developers (sic) site, but that data can't be trusted either since it changes so frequently and so little care is given to getting it right.
This is just spelling / grammar, I have no problems with these errors, especially when the main documentation is wiki-based (this may be because I'm not a native speaker). In my limited experience with Facebook docs before the Open Graph API, I haven't seen factual errors, but there are a lot of omissions.
Open Graph API seems very clean and it also seems like it doesn't need much documentation... if the API calls actually worked. I haven't used it and I don't plan to start using it given these reports (in the old API there were also quite a few things that break occasionally and take forever to be repaired).
I wrote a simple plugin to update Facebook and Twitter statuses when I published a new post in WordPress. Simply authenticating to Facebook took about 2 hours of work, following API links that no longer worked and linked to Bing searches, etc. Problem is, I always swear never to write code on Facebook anymore after one of these experiences, but the next month...
I couldn't agree more with this article (though I sadly can't say 'no' to Facebook development). I recently did a tiny amount of Facebook integration into a site and it was horrific.
All I wanted to do was add a `Like` button that would broadcast to the clicker's friends timeline. What could be simpler? Just copy and paste their code onto your page and you're done. Right?
The second sentence on their documentation page says "when the user clicks the Like button on your site, a story appears in the user's friends' News Feed with a link back to your website."
But it turns out that's not true. It turns out you have to jump through all kinds of hoops to get that behavior. The documentation for their simplest and most used integration feature couldn't go one paragraph without falsehood.
Yup, the whole point of putting a `Like` button your page is so that site visitors can broadcast your page to their friends. However, to cause that broadcast to actually occur you have to put a bunch of Open Graph meta tags on your page and also (I think?) have a registered Facebook Application to go along with your site.
There's no place that's documented except for the developer forums.
My favorite game is finding easy-to-fix bugs in the bug tracker that have thousands of votes and have been rotting away with no action for months or years.
I really don't understand how FB can have so much interest in the future of their platform but let the fruits of their labor spoil like this.
Hopefully highly read posts like this will finally bring some attention to the matter. Where are you Zuck?!%
I'm in 100% agreement with this article. My company has sold more and more Facebook app / custom tab work lately, and it amounts to nothing but headaches.
Most clients simply refuse to understand that so many of the problems encountered are Facebook's fault as a result of bugs in their system or APIs broken from upgrades.
I wouldn't wish this kind of pain on any developer.
When are you going to put the Wiki back online? That should be a matter of a few man-hours of work. Until then, it's not believable to claim "We're working on updating the site and docs as fast as we can."
In my experience developing a couple of FB apps in the past, the information in the Wiki was absolutely crucial. (I'm talking about the Wiki that was located at http://wiki.developers.facebook.com/ in the past.)
The docs are horrible and often contradictory -- but with enough trial and error most things can be figured out.
The unannounced breaking changes are absolutely inexcusable and screw the people using your platform. It is not a sustainable development plan, you will eventually alienate 'the next Zynga' and all the smaller developers. Please, please, please put some effort into API stability.
Just want to say I'm really happy you wrote this post.
Unannounced changes to the platform - breaking core things we were working with - under deadline, with a client recently resulted in one of the worst disasters I've ever had to deal with on a project. It devolved into the collapse of a startup, not getting paid for almost half of the work we did, sleepless nights trying to hack impossible workarounds, a shady last-ditch buyout deal and multiple shouting matches with otherwise rational executives over un-realized expectations.
76 comments
[ 4.7 ms ] story [ 119 ms ] threadOn a more general note, I’d strongly recommend against building your entire business around a single platform.
I see this statement a lot and I never understand it. If you're Zynga, should you build Farmville for OpenSocial and as an independent site too? The cost of doing this seems prohibitive.
Most businesses built on Facebook can be taken elsewhere if the cost of the Facebook platform starts to outweigh the benefits. Even Farmville can be ran independently, but consider how many users they'd lose in the transition and afterwards.
It is nice that there are technologies like cross-platform application framework or CSS, that let you create code for your target platform that you might just be able to port to another platform at a later date. But that doesn't take away from the fact that you're likely going to be betting on a given platform at a given time.
Perhaps what you want to say is "don't develop for a platform that will stand in the way of you porting at a later date" - indeed, all the walled-garden stuff seems to have this lock-in quality and would make sense to avoid - if you have a choice.
tl;dr: Don’t put all your eggs in one basket, especially if said basket has a history of breaking.
All of the big moneymakers' apps are built on the older stuff, so I figure when it breaks, it gets a bit more love.
The documentation is still shoddy, the Bing-powered documentation search is abysmal, and when things don't work I don't understand why. I'd have happily paid a few hundred dollars to be part of the developer program and have a contact over there, but they killed that. Ah well.
Why they dumped the only hope they had -- the wiki -- I will never understand.
It does seem as if someone over there is aware that the current situation is pretty awful, at least enough to say "we're working on it".
There still is a preferred developer program for the bigger companies out there but it doesn't really offer much of anything. Go back a year though and it was a big benefit.
http://blog.freebase.com/2010/04/29/a-freebase-implementatio...
The Facebook docs:
http://developers.facebook.com/docs/api
But even the cleanest API is of no use if the API calls don't actually work...
Also, does FQL work? I'm just starting to look at it for an app.
Guess who your users blame when all of a sudden they can't log into your site anymore with their Facebook account?
We user RPX/Janrain to deal with this, but we still get burned sometimes nonetheless.
Ww get next to nothing useful from facebook these days. Sure, we have a dedicated internal contact, but it isn't very beneficial. We hear news maybe a week before it's released to the general public, but there is no feedback from them on critical regressions that affect our business. Facebook is pretty much a black hole when it comes to communication.
Oh, the irony.
Ironically (or maybe not), part of the presentation was a slide featuring a workgroup with a "Done is better than perfect" poster. Well, yeah, but when you're running a platform service...
I found myself at times resorting the trawling through js source to find how I could use certain button images that were very simple in the old version.
I feel your frustration and am glad I don't really have to do much in the facebook space at the moment.
Hiring a tech writer and sending your lead dev to scrum school won't help either. You need to value good work at work. If you're too busy worrying about how to skim by with less money or worried about losing your employees, you're too distracted. Work with fewer people, get less done, but make sure you do it right! Why do people need a primer on this? It is just common sense.
Several people have mentioned how bad the documentation is, but nobody has provided examples. In case anyone from Facebook (or "facebook" as it's sometimes called in the docs) reads this and cares, I'm putting some examples from the docs below.
The problem with having mistakes in the docs, is that as the reader notices more and more mistakes, they begin to have less and less confidence in everything that is written there. Once the documentation is suspect, every word in it is suspect.
Here's an example of a sentence lifted from the docs: "i whose fields and values can be inspected and accessed."
Yes, that was the entire sentence, if you can call it that.
How about: "Application can implement these interface to handle them."
Seems like a small error, but a more important message is given to the reader: You cannot trust this document.
Just to preempt an obvious reaction, yes, you shouldn't trust any document, but there are levels of trust, and this kind of grammar makes the trust fall quickly to a very low level.
Another one: "The FBSessionDelegate is a callback interface that your application should implement: it's methods will be invoked when the application successful login or logout."
Same message there. You can't trust this.
Then there are the code examples. Here's their example of how to use something the docs call a stream.publish flow:
NSMutableDictionary* params = [NSMutableDictionary dictionaryWithObjectsAndKeys: apiKey, @"api_key", nil]; [facebook dialog: @"stream.publish" andParams: params andDelegate:self];
Ignoring the bizarre inconsistent use of spaces after colons, this example gives no clue about what else should be in the params object in order to make a publishable post. I could look it up on the Facebook developers (sic) site, but that data can't be trusted either since it changes so frequently and so little care is given to getting it right.
</rant>
Open Graph API seems very clean and it also seems like it doesn't need much documentation... if the API calls actually worked. I haven't used it and I don't plan to start using it given these reports (in the old API there were also quite a few things that break occasionally and take forever to be repaired).
Some syntactic errors are so egregious as to obscure, change, or remove the meaning of a sentence.
Graph API - The Facebook API for querying the Facebook graph
Open Graph Protocol - The "standard" for be able to query meta and classify a particular website.
All I wanted to do was add a `Like` button that would broadcast to the clicker's friends timeline. What could be simpler? Just copy and paste their code onto your page and you're done. Right?
The second sentence on their documentation page says "when the user clicks the Like button on your site, a story appears in the user's friends' News Feed with a link back to your website."
But it turns out that's not true. It turns out you have to jump through all kinds of hoops to get that behavior. The documentation for their simplest and most used integration feature couldn't go one paragraph without falsehood.
There's no place that's documented except for the developer forums.
Can you please elaborate on this? I thought it was just the meta tags that were needed?
I really don't understand how FB can have so much interest in the future of their platform but let the fruits of their labor spoil like this.
Hopefully highly read posts like this will finally bring some attention to the matter. Where are you Zuck?!%
Most clients simply refuse to understand that so many of the problems encountered are Facebook's fault as a result of bugs in their system or APIs broken from upgrades.
I wouldn't wish this kind of pain on any developer.
Fortunately, I get to do something about it.
I work for Facebook (joined ~3 weeks ago).
Part of my job is to help fix the developer site, documentation, etc. (along with a host of other issues related to developer relations).
We are working on updating the site and docs as fast as we can and this thread is helpful.
If you have any issues/feedback/whatever with our platform docs or API, email me at dmp@facebook.com and we'll get them addressed as soon as we can.
In my experience developing a couple of FB apps in the past, the information in the Wiki was absolutely crucial. (I'm talking about the Wiki that was located at http://wiki.developers.facebook.com/ in the past.)
The unannounced breaking changes are absolutely inexcusable and screw the people using your platform. It is not a sustainable development plan, you will eventually alienate 'the next Zynga' and all the smaller developers. Please, please, please put some effort into API stability.
One can only hope.
Unannounced changes to the platform - breaking core things we were working with - under deadline, with a client recently resulted in one of the worst disasters I've ever had to deal with on a project. It devolved into the collapse of a startup, not getting paid for almost half of the work we did, sleepless nights trying to hack impossible workarounds, a shady last-ditch buyout deal and multiple shouting matches with otherwise rational executives over un-realized expectations.
Facebook, get your freakin act together.
So, can I have your clients, then? =)