Hacker Newsnew | comments | show | ask | jobs | submit login

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>




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.

-----




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact

Search: