Hacker News new | past | comments | ask | show | jobs | submit login
I’m done building Facebook apps for clients (ryanwaggoner.com)
348 points by ryanwaggoner on Sept 27, 2010 | hide | past | favorite | 76 comments

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.


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

This is just spelling / grammar

Some syntactic errors are so egregious as to obscure, change, or remove the meaning of a sentence.

I hate to be picky but it seems to be getting out of control.

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.

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.

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

It's up now!

No, it's not.

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

  I understand and am legitimately sorry for the frustration you guys are

  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



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

What an utter waste of effort! For more time spent doing grunt work, you give slower and less complete feedback to your customers (platform developers in this case). There may be some information they don't want in a public tracker, but I'm betting it's:

- a lot less information than they think; and - much easier to manage in a different way, as opposed to maintaining two bug databases!

Its great that they're trying to simplify it and use standards, its not so great that the way they've been getting there is to simply switch old things off without notice and not document or adequately announce the new ways of doing things before they launch.

Honestly, I get it but the damage has been done. The hype window surrounding the facebook platform has passed and their developer outreach effort is too little too late.

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.

I worked at a company developing proprietary image processing SDKs (more like libraries) for .NET/ActiveX. We actually had very extensive QA, probably >100% code coverage (at least 1 test for most code paths) in unit and functional tests, but it's really difficult to predict how customers are going to use your product.

For this reason, newer employees had to do a cycle of QA/support/dev, where you found out that there would always be one customer whose entire use case was the one case you didn't test for, and that makes your toolkit fail horribly. I'm not excusing these bugs, and Facebook is certainly a more complex platform to build on top of, but I can certainly see how a QA team could be working nonstop and appearing to accomplish nothing.

(Also note that since leaving this job better testing tools have come out/become more popular. The Ruby community especially is very oriented toward automating "mutate this test until it fails".)

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.

More than once, when I searched the documentation, the top result was a link to the very search page I was on.

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.

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.

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

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.

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.

So when you like something, it doesn't actually appear in friends' newsfeeds? Elaborations please.

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.

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.

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

For what it's worth, it's only five lines of meta tags that are well documented.

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

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.

If they'd done things the facebook way, they'd never have made it past DOS.

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.

"Facebook is pretty much a black hole when it comes to communication."

Oh, the irony.

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.

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.

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.

you will eventually alienate 'the next Zynga'

One can only hope.

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.

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.

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.

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.

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

With docs, correct is better than done.

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.

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

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

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

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

Explain, please?

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:


The Facebook docs:


But even the cleanest API is of no use if the API calls don't actually work...

Explain "doesn't work".

Also, does FQL work? I'm just starting to look at it for an app.

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?

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

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.

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.

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.

What actions can you do in twitter? 1. Post a tweet That's everything.

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

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

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.

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

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

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? =)

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

Perhaps a splinter of StackExchange for the Facebook APIs could be arranged?

a la http://www.joelonsoftware.com/items/2010/08/31.html

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.

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.

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

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

Facebook documentation SUCKS!

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!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact