今月上旬に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

直近数ヶ月の変更だけでこれです。けっこう多めですが、各項目に機能が増えて来たり複雑になってきて整理し直すというのは分かりますから、ある程度は仕方ありません。

改悪!!

ただ納得いかないのは、認証・認可のフロー周りのドキュメントがかなりの頻度で分割されたり構成が変わったりして、ただでさえ複雑なのが余計に分かりにくくなっている点です。たとえば今回の変更の一部だと以下のように。

b1d4703121320e07e843f2f08d0fead1

これは 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をパースする)
Games on Facebookということは、facebook.com内でiframe表示する canvas タイプのゲームアプリを指しているように見えます。ですが、signed_requestパラメータを利用するタイミングはそれだけではありません。ぱっと思いつく限りでも以下の数パターンがあります。
こうして見ると、明らかに前のタイトルの方が分かり易い気がしませんか。私ならGames on Facebookなんて書かれていたら読み飛ばしてしまいそうです。あと細かい話ですが、該当セクションに直接飛ばした場合、セクション名がヘッダに隠れてしまってちょっと分かりにくい...

まとめ

親切心から該当ドキュメントのリンクを残していても、かなり高い頻度で遷移先のページが更新されているので、その旨も共有しておかないと余計に混乱するので気をつけましょう。私が過去の仕様を確認する場合は、Wayback Machineで当初の日付前後まで遡るようにしています。そういった場合は、ドキュメントのリンクと同時にその日付も残しておくと分かり易いと思います。
95ad8ae82936a527dca619a5ed3b795b

おまけ

以下、ドキュメント周りを追って来て思う全体の流れです。
これまでの大まかな流れとしては以下のような感じ。
  1. 2009~2010年
    ドキュメントやwikiの状態が古く、リンク切れも多い状態。
    旧フォーラム(今はfacebook.stackoverflow.comへ移行)で情報交換するのが主流
  2. 2010~2011年あたり
    ドキュメントの更新が活発になり、2011年f8でのOpen Graph Action/Object発表以降は特に力を入れるようになった。
    バグ報告も外部から見えるように管理され始めた。
    stackoverflow.comで一般的な内容を聞くと怒られるので、概要についてはQuoraなどで聞く人が出てくる。
  3. 2012年後半
    /docs/howtos/* 配下に項目毎にページが置かれ、ページ毎にStep1から手順を追って解説
  4. 2013年前半
    細かい仕様については /docs/technical-guides/* 配下、概要については /docs/* 配下にまとめ始めた?