Tbpgr Blog

Employee Experience Engineer tbpgr(てぃーびー) のブログ

質が高いと噂のPHP公式リファレンスマニュアルに関する特徴をRuby使いがまとめてみた

エンジニアHubの記事でBASEのCTOである『えふしん氏』が以下のように語っているのをみました。

若手エンジニアの方々には、「公式サイトのドキュメントが優れている技術を活用すること」を勧めます。たとえば、PHPの公式マニュアルやMySQLのリファレンスマニュアルなどはすごく質が高いですよ。

えふしんに聞く「僕が若手エンジニアならこれを学ぶ!」トップランナーの考える成長戦略 - エンジニアHub|若手Webエンジニアのキャリアを考える!

ちょうどRubyの公式リファレンスマニュアルである「るりま」のサンプルコード拡充のお手伝いをはじめた私としては

「すごく質が高いリファレンスマニュアルとはどのような特徴を持つものを言っているのだろう?」

ということが気になりました。 各種言語のリファレンスに関する言及はちょくちょく見かけるのですが、
良い・悪いぐらいの粒度の情報が多く、何を持って良いのか悪いのかよくわかりませんでした。

その特徴を理解すれば、Rubyのリファレンスマニュアルを更に進化させるお手伝いができるかもしれない、
と考えたためまとめてみることにしました。

そこで、例として挙げられている PHPの公式リファレンスマニュアル の特徴を書き出してみることにしました。

PHPリファレンスマニュアルの特徴

PHP公式サイトの構成

http://php.net/

本来は言語リファレンス側のサイト構成が話題の対象ですが、導線も大事だと思うので
PHPの公式サイトのサイト構成からふれています。

  • Downloads
  • Documentation
    • 各言語(2017/10/11時点で10ヶ国語)の言語リファレンスへのリンク
    • ダウンロード版へのリンク
    • マニュアル貢献ガイドへのリンク
    • Online Documentation Editor へのリンクと説明
  • Get Involved
    • PHPへの貢献について
  • Help

言語リファレンスのトップページ

http://php.net/manual/ja/

各コンテンツへのリンク

序文

http://php.net/manual/ja/preface.php

マニュアルの目的と構成に関する説明

はじめに

http://php.net/manual/ja/getting-started.php

入門資料。

  • PHPとは何か?
  • 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

f:id:tbpg:20171011133403p:plain

検索はインクリメンタルに実行されます

f:id:tbpg:20171011133417g:plain

Edit

f:id:tbpg:20171011133433p:plain

オンライン編集機能。
特別な環境を設定しなくても貢献できるようになっている。

Report a Bug

f:id:tbpg:20171011133510p:plain

バグレポート起票画面へのリンク。
ボタンを押したページの情報が設定済みの状態で開くようになっている。

User Contributed Notes

f:id:tbpg:20171011133441p:plain

該当ページに対する改善案などのやりとりをするコメント欄があり、
各コメントに対して up vote / down vote が可能になっている。

言語機能に関するリファレンス

基本構文や型など、見出しから詳細項目へと遷移する構成になっている。

個別の項目に関するページでは説明文とサンプルコードがセットになって解説されている。 以下はString型のページです。

http://php.net/manual/ja/language.types.string.php

関数リファレンス

http://php.net/manual/ja/funcref.php

カテゴリごとの関数のリファレンスが列挙されている。

各ライブラリに関して

  • ライブラリの概要(はじめに)
  • インストール方法
  • 個別機能の説明

等が用意されています。

例えば配列なら

個別機能のページには

  • 名前
  • 対応バージョン
  • シグネチャ
  • 機能の概要説明
  • パラメータの説明
  • 返り値の説明
  • エラー例外に関する説明
  • 参考(関連リファレンスへの参照リンク)

などがあります。

まとめ

オンライン編集画面、個別ページからのバグ表の起票、充実した検索機能。
このあたりが親切であると感じました。

PHPは個別機能に対するサンプルコードが充実しているのは確かで、
その点は現在るりまのサンプルコード拡充で取り組み中なので、このまま継続すればよいかなと思いました。

tbpgr.hatenablog.com

その他に関して個別の記載内容に関しては、Rubyリファレンスマニュアル(るりま)とどのような差異があるのか、
はっきりと確認できなかったので、ブクマやツイートなどでの意見を期待しています!
他にも「XXX言語のリファレンスはこんなところがすごいよ!」というような他言語の情報も期待しています。

関連