
I’m done building Facebook apps for clients - ryanwaggoner
http://ryanwaggoner.com/2010/09/im-done-building-facebook-apps-for-clients/
======
natch
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
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).

~~~
kd0amg
_This is just spelling / grammar_

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

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

~~~
someone_here
It's up now!

~~~
kragen
No, it's not.

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

~~~
onewland
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".)

------
andrewf
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
More than once, when I searched the documentation, the top result was a link
to the very search page I was on.

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

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

------
Gobiner
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
So when you like something, it doesn't actually appear in friends' newsfeeds?
Elaborations please.

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

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

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

~~~
jsankey
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
If they'd done things the facebook way, they'd never have made it past DOS.

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

------
sofuture
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
_you will eventually alienate 'the next Zynga'_

One can only hope.

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

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

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

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

------
bryne
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
With docs, correct is better than done.

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

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

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

------
ntoshev
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
Explain, please?

~~~
ntoshev
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-
implementatio...](http://blog.freebase.com/2010/04/29/a-freebase-
implementation-of-the-facebook-graph-api/)

The Facebook docs:

<http://developers.facebook.com/docs/api>

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

~~~
joe_the_user
Explain "doesn't work".

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

------
empika
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_

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

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

------
pxlpshr
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
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
What actions can you do in twitter? 1\. Post a tweet That's everything.

~~~
neilcrookes
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 ;-)

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

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

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

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

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

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

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

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

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

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

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

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

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

------
flexterra
Facebook documentation SUCKS!

~~~
user24
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
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!

