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.
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.
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 email@example.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.)
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,
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
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!
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.
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.
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".)
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.
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.
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".
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.
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?
On 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.
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.
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.
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?!%
The Facebook docs:
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.
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