今月上旬にFacebook::OpenGraph 1.00を出しました。Facebook Platformの定める主要な機能を実装しおわった状態で、利用法をまとめたCookbookや日本語版PODのJA.podは置かれていないのですが、利用法は t/ 配下のテストを見て頂くと分かると思います。が、今回はモジュール本体についての話ではなく、ドキュメントのURLとか名称とか構成が変わりすぎて腹が立った話です。
公式ドキュメントへのリンク
Facebook::OpenGraphでは、本家ドキュメントURLや ドキュメントの要所要所の引用をコード中にコメントとして残しています。POD中にも概要ページへのリンクなど残してあるのですが、そちらはあくまでモジュールの使い方が中心で、細かい実装面については以下のようにコード中で参照しているという具合です。# ページ名: セクション名
# https://developers.facebook.com/該当ページのパス
sub method_name {
my ($self, $foo) = @_;
# 仕様の抜粋
........
}
ですが、こうしてリンクを残していても、リンク先ページはしょっちゅう変わってしまいます。たとえば、コメントで参照しているURLを最新のものに置き換えた結果がこちら。Update document links · 957ab92 · oklahomer/p5-Facebook-OpenGraph · GitHub
直近数ヶ月の変更だけでこれです。けっこう多めですが、各項目に機能が増えて来たり複雑になってきて整理し直すというのは分かりますから、ある程度は仕方ありません。
改悪!!
ただ納得いかないのは、認証・認可のフロー周りのドキュメントがかなりの頻度で分割されたり構成が変わったりして、ただでさえ複雑なのが余計に分かりにくくなっている点です。たとえば今回の変更の一部だと以下のように。これは signed_request をパースする箇所なのですが、去年後半のドキュメントは"Using the signed_request Parameter(signed_requestパラメータを利用する)"というタイトルで、該当セクションの名前は"Parse the signed_reqeust(signed_reqeustをパースする)"でした。これはとても分かり易いと思います。
で、変更後は以下の通り。
- ページ名:Using Login with Games on Facebook(Facebook上のゲームにログインする)
- セクション名:Parsing the Signed Request(Signed Requestをパースする)
- ゲーム以外のcanvasアプリ
- ページタブアプリ
- JS SDKとPHP SDKを併用している場合 (JS SDKでFB.init() した際にクッキーがセットされ、PHP SDK内でそこから復元する)
- 「単なる OAuth 2.0 を認証に使うと、車が通れるほどのどでかいセキュリティー・ホールができる」で紹介されているように、scope=signed_requestを指定している
- ユーザの状態変更の通知を受け取る場合(ユーザがFacebookアプリを削除したときに通知を受けるには)
まとめ
親切心から該当ドキュメントのリンクを残していても、かなり高い頻度で遷移先のページが更新されているので、その旨も共有しておかないと余計に混乱するので気をつけましょう。私が過去の仕様を確認する場合は、Wayback Machineで当初の日付前後まで遡るようにしています。そういった場合は、ドキュメントのリンクと同時にその日付も残しておくと分かり易いと思います。おまけ
以下、ドキュメント周りを追って来て思う全体の流れです。これまでの大まかな流れとしては以下のような感じ。
- 2009~2010年
ドキュメントやwikiの状態が古く、リンク切れも多い状態。
旧フォーラム(今はfacebook.stackoverflow.comへ移行)で情報交換するのが主流 - 2010~2011年あたり
ドキュメントの更新が活発になり、2011年f8でのOpen Graph Action/Object発表以降は特に力を入れるようになった。
バグ報告も外部から見えるように管理され始めた。
stackoverflow.comで一般的な内容を聞くと怒られるので、概要についてはQuoraなどで聞く人が出てくる。 - 2012年後半
/docs/howtos/* 配下に項目毎にページが置かれ、ページ毎にStep1から手順を追って解説 - 2013年前半
細かい仕様については /docs/technical-guides/* 配下、概要については /docs/* 配下にまとめ始めた?