10 ms·

I’m done building Facebook apps for clients

348 points by ryanwaggoner 16y ago

zacharyvoase 16y ago
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.
- ntoshev 16y ago
  > 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.
- joe_the_user 16y ago
  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.
- zacharyvoase 16y ago
  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.
andrewf 16y ago
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.
- nfriedly 16y ago
  More than once, when I searched the documentation, the top result was a link to the very search page I was on.
  - tlack 16y ago
    I just started noticing that about two weeks ago. What an monumental pile of failure those docs are. Why they dumped the only hope they had -- the wiki -- I will never understand.
- bryne 16y ago
  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".
- fbdev 16y ago
  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.
ntoshev 16y ago
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...
- Tichy 16y ago
  Explain, please?
  - dmose 16y ago
    http://en.wikipedia.org/wiki/Bret_Taylor http://en.wikipedia.org/wiki/Bret_Taylor
    - Tichy 16y ago
      It doesn't say anything about the API. Is there a spec for the API that is independent from Facebook? Is it creative commons/open source?
  - ntoshev 16y ago
    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: http://blog.freebase.com/2010/04/29/a-freebase-implementation-of-the-facebook-graph-api/ http://blog.freebase.com/2010/04/29/a-freebase-implementatio... The Facebook docs: http://developers.facebook.com/docs/api http://developers.facebook.com/docs/api But even the cleanest API is of no use if the API calls don't actually work...
    - joe_the_user 16y ago
      Explain "doesn't work". Also, does FQL work? I'm just starting to look at it for an app.
- kragen 16y ago
  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).
emullet 16y ago
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.
shawnwall 16y ago
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.
MicahWedemeyer 16y ago
This also applies to login via Facebook Connect. They change the rules on this sometimes, and don't give much warning beyond a post on their dev blog. 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.
flexterra 16y ago
Facebook documentation SUCKS!
- user24 16y ago
  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.
  - ryanwaggoner 16y ago
    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!
ojbyrne 16y ago
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.
- robryan 16y ago
  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.
- jsankey 16y ago
  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.
  - stretchwithme 16y ago
    If they'd done things the facebook way, they'd never have made it past DOS.
- fbdev 16y ago
  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.
  - 16y ago
bryne 16y ago
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...
- natch 16y ago
  With docs, correct is better than done.
nicholaides 16y ago
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.
pxlpshr 16y ago
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.
- robryan 16y ago
  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.
  - bananaandapple 16y ago
    What actions can you do in twitter? 1. Post a tweet That's everything.
    - neilcrookes 16y ago
      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 ;-)
robryan 16y ago
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.
devmonk 16y ago
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.
natch 16y ago
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: 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>
- ntoshev 16y ago
  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).
markbao 16y ago
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...
pibefision 16y ago
For Rails: Devise 1.1.2 + MiniFB (both on Rails3) works very well.
Gobiner 16y ago
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.
- bemmu 16y ago
  So when you like something, it doesn't actually appear in friends' newsfeeds? Elaborations please.
  - far33d 16y ago
    It does - I think the OP is referring to all the open graph data you need to add to your page to have this functionality work properly.
    - Gobiner 16y ago
      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.
      - steve19 16y ago
        > also (I think?) have a registered Facebook Application to go along with your site. Can you please elaborate on this? I thought it was just the meta tags that were needed?
stilist 16y ago
A few months ago we developed our first Facebook application for a client. It was such an awful experience that I suspect it may be our last.
tlack 16y ago
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?!%
bgentry 16y ago
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.
douglasp 16y ago
I agree with most of the comments here and on the blog post; having hit many of the same issues myself. 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.
- kragen 16y ago
  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/ http://wiki.developers.facebook.com/ in the past.)
  - someone_here 16y ago
    It's up now!
    - kragen 16y ago
      No, it's not.
sofuture 16y ago
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.
- MartinCron 16y ago
  you will eventually alienate 'the next Zynga' One can only hope.
rwhitman 16y ago
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. Facebook, get your freakin act together.
vishaldpatel 16y ago
Really sorry about you giving up an income stream - I hope you've found other, better, more rewarding projects to work on. So, can I have your clients, then? =)
VladRussian 16y ago
this is the thing about monopoly - the only recourse one has against it is to whine.
empika 16y ago
I have to use the Facebook api for work. I have asked that I no longer have anything to do with Facebook development due the the immense stress it causes, seriously, just thinking about it can put me in a bad mood. unfortunately this isnt really an option so im stuck with it sadface
seancron 16y ago
In case anyone didn't see it down at the bottom, this comment was left on the post: Ryan (& Everyone Else) – My name is Mike Vernal, and I manage the engineering team for Facebook Platform. I understand and am legitimately sorry for the frustration you guys are experiencing. I think there were three themes in this post — frequency of change, bugs, and documentation. I wanted to give you some more context on all three points, not as a way of excusing the problems you’ve had but as a way of adding some additional context. Over the past year or so, we’ve been pushing to simplify and standardize our development platform as much as possible, to address some of the root causes of the issues you point out here. For instance, we’ve been trying to move from FBML to IFrames over the past year because we think that IFrames are both a lot simpler to develop for and a lot simpler to maintain because they’re based on standard web technologies. We’ve also been moving towards simpler ways of integrating Facebook context (e.g., iframe-based social plugins) because they’re easier to use, debug, and maintain. Our end goal is to have a technology stack that is simple and standards-based, because we believe that’s actually the best way to address many of the issues you raise here. In terms of bugs, you’re right — we haven’t been doing a good enough job here. We’re working on this. We’re triaging bugs on a daily basis and working through the bug backlog. We’re continually adding more automated unit + functional tests to help prevent regressions and issues in the first place. And we’re working on our communication processes — the way the system works today, we actually copy verified bugs from Bugzilla into an internal bug tracking system, and we then use that internal bug tracking system to drive bugs to resolution. We don’t do a good enough job of communicating back to the Bugzilla bug the internal status and when we actually push a fix, which we’re working on. In terms of documentation, again, you’re right. We’re building up a team and focusing on this as well. That said, actions speak louder than words. If you don’t see meaningful improvement by the end of October, please let me know. My email is mvernal@facebook.com. Thanks, -mike
- krobertson 16y ago
  Very interesting. As an FB developer, some of the bugs they introduce (and re-introduce) are baffling. Their QA process always appears non-existant. I'd like to believe him, but would have to see it first. We often file bugs that sit there forever, and some parts of their platform break on a weekly cycle, if not more often.
code_duck 16y ago
Yeah, it's bad enough developing your own applications on someone else's unstable API - I'd definitely hate to do it as client work.
joe_the_user 16y ago
In a sadly ironic fashion, a lousy API, that makes you invest months on kludging your code, can tie a company or developer to a platform. This was a factor with Microsoft's domination. How much do you think this is a factor with Facebook.
2lik 16y ago
Don't forget the awesome recent and upcoming changes: http://dipinsi.de/post/1166448458/things-they-wont-tell-you-new-facebook-policies http://dipinsi.de/post/1166448458/things-they-wont-tell-you-...
hello_moto 16y ago
I'm actually quite surprised that HN-ers are complaining about Facebook API, documentation, and quality assurance process. Isn't Facebook the kind of companies where most HN-ers fall in love with? 1) Young founder with visions 2) Hacking culture (to the max) 3) Cool technology (Erlang, C++, Java, Hadoop, HBase) Every time I saw a Facebook engineer giving a talk or writing a blog, the word "quality" (unit test, test, automation, manual, or whatever) and "documentation" are nowhere to be found. It's not in the company's blood/gene when it comes to QA process. Maybe that's the reason why they're hiring super smart and super young individuals? to pull all-nighters fixing bugs and pray during the release day? It'll be super hard to get better in QA because it's probably too late for them: too many hot-shot developers who aren't used to testing (automated or manual). They'll probably hire tons QA and automation engineers, but at the end of the day, their developers will "fix" bugs and throw it over the wall. Some people might not like the way Google works (too much bureaucracy in terms of code quality), but they work really hard to make sure their engineers are responsible toward the code they produce. It's hard to have that kind of mentality embedded onto your engineers.
mattmaroon 16y ago
I really didn't understand why they deprecated the wiki. It makes as little sense as the way programmers misuse the word deprecate.
stretchwithme 16y ago
Whenever I encounter a site that gives me many ways to login, I click the Facebook icon just for the heck of it. And when it fails, one can only conclude: situation normal
tezza 16y ago
Perhaps a splinter of StackExchange for the Facebook APIs could be arranged? a la http://www.joelonsoftware.com/items/2010/08/31.html http://www.joelonsoftware.com/items/2010/08/31.html
waterlesscloud 16y ago
So here's the obvious way for someone to beat Facebook.
vondip 16y ago
I love this thread. The last six month of frustration finally have a place to express itself. I found Facebook's documentation to be awful, and their online tools not very clear \ friendly. What I did find immensely useful is the community's support and knowledge. SO is filled with excellent questions and “How To”s. Also Facebook's developer forum is quite good. In other words, my fellow developers... keep on the good work, help build a strong community, Facebook sure isn't.

348 points by ryanwaggoner 16y ago

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.

ntoshev 16y ago
> 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.
joe_the_user 16y ago
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.
zacharyvoase 16y ago
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.

andrewf 16y ago

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.

nfriedly 16y ago
More than once, when I searched the documentation, the top result was a link to the very search page I was on.
- tlack 16y ago
  I just started noticing that about two weeks ago. What an monumental pile of failure those docs are. Why they dumped the only hope they had -- the wiki -- I will never understand.
bryne 16y ago
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".
fbdev 16y ago
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.

ntoshev 16y ago

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...

Tichy 16y ago
Explain, please?
- dmose 16y ago
  http://en.wikipedia.org/wiki/Bret_Taylor http://en.wikipedia.org/wiki/Bret_Taylor
  - Tichy 16y ago
    It doesn't say anything about the API. Is there a spec for the API that is independent from Facebook? Is it creative commons/open source?
- ntoshev 16y ago
  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: http://blog.freebase.com/2010/04/29/a-freebase-implementation-of-the-facebook-graph-api/ http://blog.freebase.com/2010/04/29/a-freebase-implementatio... The Facebook docs: http://developers.facebook.com/docs/api http://developers.facebook.com/docs/api But even the cleanest API is of no use if the API calls don't actually work...
  - joe_the_user 16y ago
    Explain "doesn't work". Also, does FQL work? I'm just starting to look at it for an app.
kragen 16y ago
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).

emullet 16y ago

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.

shawnwall 16y ago

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.

MicahWedemeyer 16y ago

This also applies to login via Facebook Connect. They change the rules on this sometimes, and don't give much warning beyond a post on their dev blog. 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.

flexterra 16y ago

Facebook documentation SUCKS!

user24 16y ago
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.
- ryanwaggoner 16y ago
  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!

ojbyrne 16y ago

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.

robryan 16y ago
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.
jsankey 16y ago
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.
- stretchwithme 16y ago
  If they'd done things the facebook way, they'd never have made it past DOS.
fbdev 16y ago
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.
- 16y ago

bryne 16y ago

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...

natch 16y ago
With docs, correct is better than done.

nicholaides 16y ago

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.

pxlpshr 16y ago

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.

robryan 16y ago
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.
- bananaandapple 16y ago
  What actions can you do in twitter? 1. Post a tweet That's everything.
  - neilcrookes 16y ago
    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 ;-)

robryan 16y ago

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.

devmonk 16y ago

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.

natch 16y ago

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: 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>

ntoshev 16y ago
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).

markbao 16y ago

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...

pibefision 16y ago

For Rails: Devise 1.1.2 + MiniFB (both on Rails3) works very well.

Gobiner 16y ago

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.

bemmu 16y ago
So when you like something, it doesn't actually appear in friends' newsfeeds? Elaborations please.
- far33d 16y ago
  It does - I think the OP is referring to all the open graph data you need to add to your page to have this functionality work properly.
  - Gobiner 16y ago
    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.
    - steve19 16y ago
      > also (I think?) have a registered Facebook Application to go along with your site. Can you please elaborate on this? I thought it was just the meta tags that were needed?

stilist 16y ago

A few months ago we developed our first Facebook application for a client. It was such an awful experience that I suspect it may be our last.

tlack 16y ago

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?!%

bgentry 16y ago

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.

douglasp 16y ago

I agree with most of the comments here and on the blog post; having hit many of the same issues myself. 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.

kragen 16y ago
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/ http://wiki.developers.facebook.com/ in the past.)
- someone_here 16y ago
  It's up now!
  - kragen 16y ago
    No, it's not.

sofuture 16y ago

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.

MartinCron 16y ago
you will eventually alienate 'the next Zynga' One can only hope.

rwhitman 16y ago

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. Facebook, get your freakin act together.

vishaldpatel 16y ago

Really sorry about you giving up an income stream - I hope you've found other, better, more rewarding projects to work on. So, can I have your clients, then? =)

VladRussian 16y ago

this is the thing about monopoly - the only recourse one has against it is to whine.

empika 16y ago

I have to use the Facebook api for work. I have asked that I no longer have anything to do with Facebook development due the the immense stress it causes, seriously, just thinking about it can put me in a bad mood. unfortunately this isnt really an option so im stuck with it sadface

seancron 16y ago

In case anyone didn't see it down at the bottom, this comment was left on the post: Ryan (& Everyone Else) – My name is Mike Vernal, and I manage the engineering team for Facebook Platform. I understand and am legitimately sorry for the frustration you guys are experiencing. I think there were three themes in this post — frequency of change, bugs, and documentation. I wanted to give you some more context on all three points, not as a way of excusing the problems you’ve had but as a way of adding some additional context. Over the past year or so, we’ve been pushing to simplify and standardize our development platform as much as possible, to address some of the root causes of the issues you point out here. For instance, we’ve been trying to move from FBML to IFrames over the past year because we think that IFrames are both a lot simpler to develop for and a lot simpler to maintain because they’re based on standard web technologies. We’ve also been moving towards simpler ways of integrating Facebook context (e.g., iframe-based social plugins) because they’re easier to use, debug, and maintain. Our end goal is to have a technology stack that is simple and standards-based, because we believe that’s actually the best way to address many of the issues you raise here. In terms of bugs, you’re right — we haven’t been doing a good enough job here. We’re working on this. We’re triaging bugs on a daily basis and working through the bug backlog. We’re continually adding more automated unit + functional tests to help prevent regressions and issues in the first place. And we’re working on our communication processes — the way the system works today, we actually copy verified bugs from Bugzilla into an internal bug tracking system, and we then use that internal bug tracking system to drive bugs to resolution. We don’t do a good enough job of communicating back to the Bugzilla bug the internal status and when we actually push a fix, which we’re working on. In terms of documentation, again, you’re right. We’re building up a team and focusing on this as well. That said, actions speak louder than words. If you don’t see meaningful improvement by the end of October, please let me know. My email is mvernal@facebook.com. Thanks, -mike

krobertson 16y ago
Very interesting. As an FB developer, some of the bugs they introduce (and re-introduce) are baffling. Their QA process always appears non-existant. I'd like to believe him, but would have to see it first. We often file bugs that sit there forever, and some parts of their platform break on a weekly cycle, if not more often.

code_duck 16y ago

Yeah, it's bad enough developing your own applications on someone else's unstable API - I'd definitely hate to do it as client work.

joe_the_user 16y ago

In a sadly ironic fashion, a lousy API, that makes you invest months on kludging your code, can tie a company or developer to a platform. This was a factor with Microsoft's domination. How much do you think this is a factor with Facebook.

2lik 16y ago

Don't forget the awesome recent and upcoming changes: http://dipinsi.de/post/1166448458/things-they-wont-tell-you-new-facebook-policies http://dipinsi.de/post/1166448458/things-they-wont-tell-you-...

hello_moto 16y ago

I'm actually quite surprised that HN-ers are complaining about Facebook API, documentation, and quality assurance process. Isn't Facebook the kind of companies where most HN-ers fall in love with? 1) Young founder with visions 2) Hacking culture (to the max) 3) Cool technology (Erlang, C++, Java, Hadoop, HBase) Every time I saw a Facebook engineer giving a talk or writing a blog, the word "quality" (unit test, test, automation, manual, or whatever) and "documentation" are nowhere to be found. It's not in the company's blood/gene when it comes to QA process. Maybe that's the reason why they're hiring super smart and super young individuals? to pull all-nighters fixing bugs and pray during the release day? It'll be super hard to get better in QA because it's probably too late for them: too many hot-shot developers who aren't used to testing (automated or manual). They'll probably hire tons QA and automation engineers, but at the end of the day, their developers will "fix" bugs and throw it over the wall. Some people might not like the way Google works (too much bureaucracy in terms of code quality), but they work really hard to make sure their engineers are responsible toward the code they produce. It's hard to have that kind of mentality embedded onto your engineers.

mattmaroon 16y ago

I really didn't understand why they deprecated the wiki. It makes as little sense as the way programmers misuse the word deprecate.

stretchwithme 16y ago

Whenever I encounter a site that gives me many ways to login, I click the Facebook icon just for the heck of it. And when it fails, one can only conclude: situation normal

tezza 16y ago

Perhaps a splinter of StackExchange for the Facebook APIs could be arranged? a la http://www.joelonsoftware.com/items/2010/08/31.html http://www.joelonsoftware.com/items/2010/08/31.html

waterlesscloud 16y ago

So here's the obvious way for someone to beat Facebook.

vondip 16y ago

I love this thread. The last six month of frustration finally have a place to express itself. I found Facebook's documentation to be awful, and their online tools not very clear \ friendly. What I did find immensely useful is the community's support and knowledge. SO is filled with excellent questions and “How To”s. Also Facebook's developer forum is quite good. In other words, my fellow developers... keep on the good work, help build a strong community, Facebook sure isn't.