I’m done building Facebook apps for clients

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>

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.

  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

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.

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.

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.

On a more general note, I’d strongly recommend against building your entire business around a single platform.

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.

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.

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.

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.

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

This was a factor with Microsoft's domination.

How much do you think this is a factor with Facebook.

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.

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.

And when it fails, one can only conclude: situation normal

So, can I have your clients, then? =)

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