Why people think Facebook Documentation sucks

From time to time, there are people complaining about Facebook dev documentation.

Frankly speaking, although Facebook dev documentation is not of top quality, it is still not the worst.  If I am to give a rating on it, I will rate it with 6/10.

But why so many people complains about that?  I think this is because of the following reasons:

  • There is no simple step-by-step / starter’s guide.
    In such a case, for those novice developers, they will get lost easily and don’t know how to start doing development on the Facebook platform.
  • Facebook is not updating their documentation “fast enough”.
    There are so many cases whether we see outdated documentation.  In such a case, thing won’t work if you follow that outdated info.
    ** I think Facebook has been improving on this area.
  • Facebook’s Terminology is not that well-defined
    Sometimes, different wordings are used to refer to the same thing / concept.  For example, I have been seeing people using words like “feed”, “wall post”, “post”, “stream”, “attachment” referring to the “wall post” that an app published to the user’s wall.  I cannot say Facebook is responsible for that.  However, we also see similar cases in Facebook documentation.
    Another well know example should be the “php lib”.  Does this refers to the PHP SDK?  or the Old PHP client library?  It is even more misleading as both “php libs” are using faecbook.php!
  • Platform stability
    Sometimes, the platform is working in a fuzzy way.  The errors are not reported in a unified way.  Therefore, people may think that they get problem simply because it is their own coding issue / problem bug.  They check against the documentation.  However, because of the “bad reputation” and “bad quality”, people is having a difficult situation.  So finally, there are cases where people simply think the documentation sucks as they cannot get their app working smoothly.
  • People rely too much on “sample code”
    Even in the forum, there are so many people simply ask “please give me a sample code to do xxxxx”.  Well, while Facebook platform can be invoked by apps / services written in a large variety of language or platform, Facebook has chosen to illustrate their API interfaces by using curl or http links.   I think this is a good choice.  But definitely not for those people that always look for sample code.

Facebook documentation has been improving…. and if you find any mistake in it, do help to open a bug report in Facebook’s bugzilla.  I am sure that Facebook team will handle that accordingly – as I have reported to them a few mistakes in the documentation and they have updated them in a reasonable time-frame.

 

This entry was posted in Development Tips. Bookmark the permalink.

One Response to Why people think Facebook Documentation sucks

  1. John says:

    I think they approach it from the viewpoint of a facebook expert. The devs have an expectation the EVERYBODY spent countless hours fooling with facebook & are very familiar with all the terminology it uses. For example the timeline: everybody knows where the timeline is & how to add to it. Thus all documentation on that subject just goes further. They don’t cater to the person tring to figure out what the timeline is.

Leave a Reply

Your email address will not be published. Required fields are marked *