先に謝っておきますと「ボランティアの開発者に失礼だ」とか「ソースがあるんだから読め」とか「困ってるなら自分で行動して貢献しろ」とかの罵倒が山ほどくるのはわかってます。ええ、もう好き放題罵倒して頂いて結構ですので、罵倒したらこんなところには二度とこないでいただけますと助かります。言い訳しときますと、別に私はこうなるべきだとか、自分の理想になってないからけしからんとか言いたいわけでは無くて、単に今自分がこういうことで困ってるなという気持ちを書き出しておきたいだけなんです。でもまあ、実際にOSSの開発者の方はこれ読んだら気分を害するとは思いますので、申し訳ないとは思います。ごめんなさい。
という言い訳を書いておいてからの本題です。要するにですね、OSSの言語とかライブラリとか使って開発してて、公式ドキュメントがいまいち整備されてなくて使い方が分からなくて不便なことがあるなぁって話なんです。まあ言ってしまえばそれだけ。困ってるんだったら自分がドキュメント書いてプロジェクトに貢献すればいいだろうというのはその通りなんで、出来る範囲でやりたいなとは思ってはいますが、実際に行動に移せているわけではないです。すいません。
とはいえ、ある程度のドキュメントはあるんですよ。チュートリアルとかもあったりするので、一通りの使い方は分かったりするんですが、そうしたドキュメントだけでは細かい使い方がわからない。全てのパラメータの全ての意味が解説してあるわけではないし、異常時にどういう挙動を起こすかなんてむしろ書いてあるドキュメントの方が珍しいというのが個人的な感覚です。まあわかりますよ。ドキュメントを一生懸命書くよりもコード書いてる方が楽しいですし、そもそもコードもまだまだ実装すべきところがあるわけですから。だからどうしたってドキュメントが後回しになるのはわかるけど、そうするとその言語やライブラリを利用する開発者が困ってしまう。
そして公式ドキュメントが不十分なこともあり、ぐぐったらアフィリエイトブログが大量にヒットしたりするのが現状です。そうしたアフィリエイトブログの解説記事でわかることもあるんですが、所詮は二次資料でしかないので、出来れば公式の一次資料で確認したいなぁとも思うわけですよ。そしてアフィリエイトブログでは結局知りたいことは分からないことがほとんど。
OSSなんだからソースを読めばいいだろうというのはその通りで、実際に困ったときにはソース読みます。ただ、ソースってあくまでも今の実装の確認でしかないじゃないですか。現在たまたまこういう実装になってるだけなのか、将来的に変わることがあるのかってのはソースからは読み取れない。極端な話、バグってて今の実装になってるかもしれない。その点で信頼できるのって結局公式ドキュメントなんですよ。公式ドキュメントに書いてあることはそう簡単には覆らないことが期待できる。それに比べるとソースは覆る可能性で公式ドキュメントよりも一段劣る。アフィリエイトブログよりはよっぽどマシではありますけどね。
今はどうか知りませんが、昔にVisualC++で開発してた頃はマイクロソフトのドキュメントにお世話になりました。当時は悪評高かったですが、いまにして思えば情報が充実してたなと思います。記憶が美化されてる可能性もありますけれど。お金をとってビジネスでやってるマイクロソフトと、無償のボランティアのOSSを比べるなってのはもっともなんですが、それは提供側の視点なんですよね。利用者としては、誰がどういう動機で作ったものかなんて極端な話どうでもいいわけで、便利な方がありがたいんですよ。その便利になるために、ではプロジェクトに寄付するとか、ドキュメント書いて貢献するかとか、まあ方法はいろいろあるんですが、どれも別レイヤの話ですよね。今現実に自分のコードを書いてるときには直接関係ない話。
この点ではPHPは比較的よくできてるなぁと思ったりもします。php.netで、基本的にはドキュメントが整備されている。そりゃマイナーな機能では不十分なところもありますけれど。でもOSSの中ではPHPは比較的ドキュメントに力を入れてるなぁという印象があります。世間的にはPHPの人気下がってるそうですけどね。みんなよく〇〇とか〇〇とかの言語で開発してるなぁと感心します。みんな実装を参照しながら書いてるんでしょうか。