エンジニアHubの記事でBASEのCTOである『えふしん氏』が以下のように語っているのをみました。
若手エンジニアの方々には、「公式サイトのドキュメントが優れている技術を活用すること」を勧めます。たとえば、PHPの公式マニュアルやMySQLのリファレンスマニュアルなどはすごく質が高いですよ。
えふしんに聞く「僕が若手エンジニアならこれを学ぶ！」トップランナーの考える成長戦略 - エンジニアHub｜若手Webエンジニアのキャリアを考える！
ちょうどRubyの公式リファレンスマニュアルである「るりま」のサンプルコード拡充のお手伝いをはじめた私としては
「すごく質が高いリファレンスマニュアルとはどのような特徴を持つものを言っているのだろう？」
ということが気になりました。
各種言語のリファレンスに関する言及はちょくちょく見かけるのですが、
良い・悪いぐらいの粒度の情報が多く、何を持って良いのか悪いのかよくわかりませんでした。
その特徴を理解すれば、Rubyのリファレンスマニュアルを更に進化させるお手伝いができるかもしれない、
と考えたためまとめてみることにしました。
そこで、例として挙げられている PHPの公式リファレンスマニュアル の特徴を書き出してみることにしました。
PHPリファレンスマニュアルの特徴
PHP公式サイトの構成
本来は言語リファレンス側のサイト構成が話題の対象ですが、導線も大事だと思うので
PHPの公式サイトのサイト構成からふれています。
- Downloads
- Documentation
- 各言語(2017/10/11時点で10ヶ国語)の言語リファレンスへのリンク
- ダウンロード版へのリンク
- マニュアル貢献ガイドへのリンク
- Online Documentation Editor へのリンクと説明
- Get Involved
- PHPへの貢献について
- Help
言語リファレンスのトップページ
各コンテンツへのリンク
序文
http://php.net/manual/ja/preface.php
マニュアルの目的と構成に関する説明
はじめに
http://php.net/manual/ja/getting-started.php
入門資料。
入門情報の最後に、入門以降の学習素材としてPHPの各種要素に関する
スライド集に誘導しています。
インストールと設定
http://php.net/manual/ja/install.php
様々な環境へのインストールや設定方法がまとまっています。
言語リファレンス
http://php.net/manual/ja/langref.php
PHPの言語の構文や標準ライブラリに関するリファレンスへのリンクがまとまっています。
すべてのページの特徴として
- Search
- Edit
- Report a Bug
- User Contributed Notes
の機能がついている。
Search
検索はインクリメンタルに実行されます
Edit
オンライン編集機能。
特別な環境を設定しなくても貢献できるようになっている。
Report a Bug
バグレポート起票画面へのリンク。
ボタンを押したページの情報が設定済みの状態で開くようになっている。
User Contributed Notes
該当ページに対する改善案などのやりとりをするコメント欄があり、
各コメントに対して up vote / down vote が可能になっている。
言語機能に関するリファレンス
基本構文や型など、見出しから詳細項目へと遷移する構成になっている。
個別の項目に関するページでは説明文とサンプルコードがセットになって解説されている。 以下はString型のページです。
http://php.net/manual/ja/language.types.string.php
関数リファレンス
http://php.net/manual/ja/funcref.php
カテゴリごとの関数のリファレンスが列挙されている。
各ライブラリに関して
- ライブラリの概要(はじめに)
- インストール方法
- 個別機能の説明
等が用意されています。
例えば配列なら
- 概要 - http://php.net/manual/ja/intro.array.php
- インストール - http://php.net/manual/ja/array.installation.php
- 個別機能の説明の例として array_chunk - http://php.net/manual/ja/function.array-chunk.php
個別機能のページには
- 名前
- 対応バージョン
- シグネチャ
- 機能の概要説明
- パラメータの説明
- 返り値の説明
- エラー例外に関する説明
- 例
- 参考（関連リファレンスへの参照リンク）
などがあります。
まとめ
オンライン編集画面、個別ページからのバグ表の起票、充実した検索機能。
このあたりが親切であると感じました。
PHPは個別機能に対するサンプルコードが充実しているのは確かで、
その点は現在るりまのサンプルコード拡充で取り組み中なので、このまま継続すればよいかなと思いました。
その他に関して個別の記載内容に関しては、Rubyリファレンスマニュアル（るりま）とどのような差異があるのか、
はっきりと確認できなかったので、ブクマやツイートなどでの意見を期待しています！
他にも「XXX言語のリファレンスはこんなところがすごいよ！」というような他言語の情報も期待しています。
