Help us understand the problem. What is going on with this article?

検索結果を要チェック!Rubyの公式リファレンスは docs.ruby-lang.org です 〜公式な情報源を調べるクセを付けよう〜

TL; DR(最初に結論)

  • たとえば、 "ruby compact" のようなキーワードで検索をかけると、公式リファレンスっぽい、非公式リファレンスがトップに表示されることがよくある
  • Rubyの公式リファレンスは docs.ruby-lang.org なので、情報の正確性を重視するならここを参照する。
  • AmiWiki(ref.xaio.jp)は非公式リファレンスかつ、何年も更新が止まっているサイトなので、このサイトを参照することは筆者としては推奨しない。
  • Rubyのリファレンスに限らず、技術情報を調べる際はそれが公式の情報源かどうかをちゃんと確認した方が良い。

はじめに

プログラミングをしていてわからないことがあると、みなさんはきっとネットで検索して調べると思います(もちろん僕も毎日調べまくってます)。
ネットを検索するといろんな情報がリストアップされますが、みなさんはその情報が信頼できる情報源かどうか、毎回確認しているでしょうか?
最も信頼できる情報源はやはり、その言語やライブラリの公式ドキュメント(公式リファレンス、公式APIドキュメント)です。

しかし、Rubyにおいては検索しても公式リファレンスが最初にヒットするとは限りません。
そのかわりに公式リファレンス風の非公式リファレンスが最初に表示されることがよくあります。(2019年11月現在の状況です)

そこでこの記事では公式リファレンスと非公式リファレンスの見分け方について説明します。

とあるユースケース「compactメソッドの仕様を調べたい!」

最初は具体的なユースケースを使って、この問題の認識を合わせたいと思います。

たとえば、あなたはRubyのcompactメソッドの仕様を知りたかったとします。
そこでブラウザの検索窓から "ruby compact" というキーワードを入力して検索ボタンをクリックしました。

以下は実際の検索結果です。(2019年11月時点の検索結果)

Screen Shot 2019-11-16 at 7.22.56.png

さて、あなたならこの中からどのリンクをクリックしますか?

AmiWiki(ref.xaio.jp)は非公式リファレンス

トップに表示されている「Rubyリファレンス - AmiWiki」というサイト(ref.xaio.jp)は、実は公式リファレンスではありません。

AmiWiki(ref.xaio.jp)を開くとこんな情報が表示されます。
Rubyをやっている人なら一度は見たことがあるのではないでしょうか?

Screen Shot 2019-11-16 at 9.27.55.png

ぱっと見は情報がきれいにまとまっていて、あたかも公式っぽく見えるのですが、このサイトは個人が管理している非公式サイトです。

このサイト「Rubyリファレンス」は、k-satoの個人的なプロジェクトです。株式会社オイアクスのサーバーを借りて、Ruby on Railsで動かしています。

https://ref.xaio.jp/ruby/about

公式リファレンスは docs.ruby-lang.org

2件目はリンクの表示を見てもサイトを開いてもQiitaであることが明らかなので、これを公式リファレンスと勘違いする人はいないと思います。

そして、3件目に表示されている docs.ruby-lang.org 。これがRubyの公式リファレンスです。
(注:Googleの検索結果には"doc"と表示されていますが、URLは"docs"なので本記事では"docs"と表記します)

クリックすると以下のような画面が表示されます。

https://docs.ruby-lang.org/ja/latest/method/Array/i/compact.html
Screen Shot 2019-11-16 at 7.36.39.png

もし "ruby compact" を検索して、先ほど見せたような結果が出てきたら、僕はこの docs.ruby-lang.org を最初にクリックします。

公式ドキュメントを参照した方がよい理由

技術情報を調べる際は、なるべく公式ドキュメントや公式リファレンスを参照するクセを付けた方がよいです。
その理由は以下のとおりです。

  • 継続してメンテナンスされているので、最新の情報が掲載されている
  • 編集する人が情報に責任を持っているので、情報が正確である

逆の言い方をすると、非公式ドキュメント(Qiitaを含む)の場合は次のような問題を抱えている可能性があります。

  • 継続してメンテナンスされているとは限らないので、古い情報をつかまされる恐れがある
  • 情報が正確かどうかは、執筆者の技術スキルや責任感に依存する

もちろん、公式ドキュメントも一部の情報が更新されていなかったり、間違いがあったりする可能性はあります(しょせん人間が管理するものなので)。
ですが、非公式ドキュメントに比べれば「ハズレ」を引く可能性は低いはずです。

AmiWiki(ref.xaio.jp)は更新が止まっているのでお勧めできない

Rubyに関して言えば、前述のAmiWiki(ref.xaio.jp)が検索結果の上位に挙がってくるため、このサイトを参照している人も多いと思います。
ですが、先ほど述べたとおり、このサイトは非公式リファレンスです。

さらに、更新履歴を見ると2012年頃で更新が止まっています。(2019年11月時点の状況です)

新しいページ

  • 2012-04-02 14:32 Insalling MacPorts
  • 2011-01-31 16:20 Mac OS Xへのインストール
  • 2010-09-08 22:00 chunk (Enumerable)
  • 2010-09-01 21:24 singleton_class (Object) -2010-09-01 12:25 keep_if (Hash)

https://ref.xaio.jp/ruby

また、サイトに記載されている対応バージョンはRuby 1.9.2までです。

対応バージョンは、1.8.6/1.8.7/1.9.1/1.9.2です。

https://ref.xaio.jp/ruby

もうすぐRuby 2.7がリリースされようとしている中で、対応バージョンがRuby 1.9というのはさすがにちょっと古すぎます。

たとえば、FixnumクラスやBignumクラスはIntegerクラスに統合されたので今のRubyには存在しませんし、Arrayクラスの便利なto_hメソッドもこのサイトには載っていません。

このように、いろいろと時代遅れな情報源になってしまっているので、個人的にはこのサイトを参照することはあまりお勧めできません。

参考情報:「Rubyの公式リファレンスはもっとSEOを向上させるべき」という意見

先日、「Rubyの公式リファレンスが検索トップに上がってこない問題」をTwitterでつぶやいたところ、 @okuramasafumi さんから次のようなリプライをもらいました。

ですので、もしかすると将来的には docs.ruby-lang.org の検索順位が上がって、うっかり非公式リファレンスを参照していた、という問題がなくなるかもしれません。

(一般論として)技術情報の公式な情報源の探し方

この記事ではRubyのリファレンスを対象にしていますが、それ以外のケースでどうやって技術情報の公式な情報源を探せば良いか、その方法を少し紹介しておきます。

公式サイトに行ってドキュメントのリンクを探す

ある程度の規模と歴史を持つプログラミング言語やフレームワークであれば、公式サイトがあると思います。
そのサイトに行けば、必ず何かしらのドキュメント情報が載っているはずです。

Rubyであれば https://www.ruby-lang.org/ という公式サイトがあります。
この中に「ドキュメント」というメニューがあるので、ここから docs.ruby-lang.org にアクセスすることができます。

Screen Shot 2019-11-16 at 10.48.36.png

Ruby on Railsであれば https://rubyonrails.org/ にGuidesやAPIというメニューがあるので、ここから公式ドキュメントを参照できます。

Screen Shot 2019-11-16 at 10.52.01.png

ちなみにご存じの方も多いと思いますが、GuidesはRailsガイドとして日本語訳されています。

https://railsguides.jp/
Screen Shot 2019-11-16 at 10.55.26.png

GitHubリポジトリのREADMEファイルを参照する

ライブラリはGitHubリポジトリで管理されていることが多いので、そこのREADMEファイルが第一の情報源となります。
このとき、最初からネットを検索してGitHubリポジトリに行ってもよいですが、 rubygems.org のような公式ホスティングサービスから「ホームページ」や「ドキュメント」のリンクを探して、そこへアクセスする方がより確実です。
(たまに、GitHub以外のネットの検索に引っかかりにくい場所にコードやリファレンスが公開されていることがあるため)

Screen Shot 2019-11-16 at 11.00.50.png

GitHubリポジトリのREADMEを読むと、ライブラリのドキュメントに関する記述がどこかにあるはずです。
僕の経験上では、以下のようなパターンが多いです。

  • READMEそのものが公式リファレンス
  • GitHub以外のサイトで公式リファレンスが公開されている(RSpecのRelishなど)
  • GitHub内のWikiに情報がまとめられている(Devise wikiなど。ただし、これは公式リファレンスというよりも追加のTips集に近いかも。DeviseにもAPIリファレンスがある)

いずれにしても、READMEには必ず何らかの情報があるはずなので、まずはREADMEをじっくり読んで、公式の情報源を探しましょう。

コード内コメントを参照する

さらに、しっかりとメンテナンスされているフレームワークやライブラリであれば、コード内にコメントとしてAPIの説明が書かれています。
ネット上に公開されている公式APIドキュメントは、このコード内コメントをHTML化しているだけ、というケースも多いです。
なので、ネット検索に頼ることなく、直接コードを読みに行く、というのもひとつの手です。

たとえば以下はRuby on Rails(正確にはActiveSupport)のblank?メソッドのコードに書かれているコメントの例です。

# An object is blank if it's false, empty, or a whitespace string.
# For example, +nil+, '', '   ', [], {}, and +false+ are all blank.
#
# This simplifies
#
#   !address || address.empty?
#
# to
#
#   address.blank?
#
# @return [true, false]
def blank?
  respond_to?(:empty?) ? !!empty? : !self
end

https://github.com/rails/rails/blob/v6.0.1/activesupport/lib/active_support/core_ext/object/blank.rb

さらに、身も蓋もないことを言えば、「コードそのものが一番信頼できるドキュメントである!だからコードを読めばすべて解決!!」という話になるのですが、それはちょっと上級者向けすぎるので、そこまでやれとは言いません😅

よくある質問

Q. 公式ドキュメント以外は参考にしちゃダメなの?

いいえ、絶対にダメというわけではありません。

非公式ドキュメント(Qiitaを含む)の方が読みやすかったり、わかりやすかったりこともあるので、僕もあえて非公式ドキュメントを参照することはあります。
ですが、その際は「もしかしたら情報が古いかも?」「もしかしたら情報が間違っているかも?」という点に十分気を付けるようにしています。

なので、みなさんも非公式ドキュメントを参照する場合は、その記事の最終更新日時はいつか?執筆者は信頼に足る人物か?といった点を確認し、不安に思うところがあれば公式ドキュメントも参考にして、その情報の正確性について裏付けを取るようにしましょう。

Q. 公式ドキュメントを読みたいけど、英語が辛いです😢

Rubyは日本生まれのプログラミング言語なので、日本語の公式ドキュメントが比較的豊富に揃っていますが、多くの場合、プログラミング言語やライブラリの公式ドキュメントは英語で書かれていることが多いと思います。

英語が苦手な人はつい日本語の非公式ドキュメントを参照したり、機械翻訳にかけたりするかもしれませんが、そうしているといつまで経っても英語のドキュメントが読めるようになりません。
この業界では「最終的に一番信頼できる情報源は英語で書かれている」というケースが大半なので、英語が苦手な人も早めに英語になれていきましょう。

ちなみに、プログラミングに関する英語は意外と毎回同じような単語が出てくるので、README等を繰り返し読んでいるうちにだんだんと辞書無しで読めるようになってくると思います。

さらに:プログラミングスクールの技術記事にも用心しよう

最近はさまざまなプログラミングスクールが技術記事を公開していることもあり(加えてSEOにもかなり力を入れているため)、こうしたサイトが検索結果の上位に挙がってくることがあります。

プログラミングスクールの技術記事はたいていデザインがオシャレで、内容も初心者向けに易しく説明されているので、こういったサイトを参考にしている人も多いかもしれません。

ですが、これらのサイトも非公式ドキュメントであることには違いがないので、情報の信頼性は公式ドキュメントよりも劣ります。

また、それだけではなく、ほぼすべての記事においてページの最後にスクールの宣伝が入っています。
つまり、そうした技術記事の目的はネット上の露出を増やして集客を向上させることだったりします。

必ずしも「プログラミングスクールの記事=信頼性が低い」ではないと思いますが、過去には、とあるプログラミングスクールが不正確な情報を掲載して炎上したケースもあります。

ですので、僕はプログラミングスクールの技術記事が検索結果に上がってくると「この記事はもしかするとスクールの宣伝が一番の目的で、技術情報の正確性は二の次になっているかも」と警戒し、なるべくクリックしないようにしています。

まとめ

というわけで、この記事ではRubyの公式リファレンスは docs.ruby-lang.org だよ、 ref.xaio.jp じゃないよ、という話を書きました。

Rubyに限らず、公式ドキュメントや公式リファレンスを参照することは遠回りなように見えて実は一番の近道だったりします。
まさに急がば回れ、っていうやつですね。

プログラミング初心者の方は「検索のトップに出てきたから」「英語じゃなく日本語のページだから」という理由だけで安易に検索結果をクリックするのではなく、 「今見ているページは公式なのか、それとも非公式なのか」「誰がいつ、どういう立場で書いた情報なのか」 といった点もちゃんと確認するようにしましょう!

Why do not you register as a user and use Qiita more conveniently?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away