公式ドキュメントを活用してみよう！

はじめに

DMM WEBCAMP Advent Calendar 2021 を担当させていただきます。
普段DMM WEBCAMPでメンターをしている小磯(@yoshikikoiso)です！
よろしくお願いします

今回は公式ドキュメントの活用方法について書いていこうと思います！

背景

私自身、コードを書いたり、普段の受講生対応の中では
Qiitaの記事を参考にすることが多いです。

ただ、周りの優秀な人たちを見ていると
そう言った人ほど当たり前のように公式ドキュメントを読みこなしているな
といった印象がありました。

ですが、

よりステップアップしていくために、
ドキュメントを読み込んでいく重要性を認識しつつも
あの独特のとっつきにくさに中々慣れず...

きっと学習されている方で同じ思いを持っている人もいるのではないかなと思いました。

そこで

・なぜ公式ドキュメントなの？わかりやすいQiitaの記事ではいけないの？
・あの公式ドキュメント独特のとっつきにくさになれないな...

と言った思いを持つ方に向け
公式ドキュメントを読むメリットや活用法などについてまとめていければなと思います。

構成

1. 公式ドキュメントとは
2. なぜ読み難さを感じるのか
3. 公式ドキュメントを活用するメリット
4. どのように活用すればいいのか
5. 最後に

1. 公式ドキュメントとは

まずはそもそもの定義から・・・

公式ドキュメントとは、プログラミング言語、フレームワーク、ライブラリについて、その公式組織が出している文書のことでプログラマ向けに書かれた説明書、兼チュートリアルです。公式ドキュメントはそれ自体が持つ特長（優れた点）、インストール方法、環境設定の方法、コードの書き方、バージョン情報などが書かれています。

とあり、大まかに言語ごとのプログラミング知識全般に関する取扱説明書のようなものだと捉えていただければと思います。

具体的にはRailsで言うと以下のようなものがあります
日本語版：https://railsdoc.com/
英語版：https://guides.rubyonrails.org/

2. なぜ読み難さを感じるのか

ここで、簡単に公式ドキュメントの説明を見てみましょう。
以下Railsドキュメントから”マイグレーション”に関する説明を抜粋させていただきます。

マイグレーションとは

説明
直接SQLを使わずに、データベースのテーブルやカラムなどの構造を変更できる仕組み

特徴
db/migrateディレクトリ以下にあるRubyで書かれたファイル
ファイル名はタイムスタンプ(西暦、月、日、時、分、秒)とアンダースコア(_)で始まり、クラス名のすべての大文字を小文字にしたもの
別々のマイグレーションファイルに同じ名前のマイグレーションクラスを記述できない
idという主キーを自動的に追加
実行するにはRakeタスク
schema_infoテーブルに現在のバージョンが格納

簡単な例

class AddSsl < ActiveRecord::Migration
  def up
    add_column :accounts, :ssl_enabled, :boolean, default: true
  end

def down
    remove_column :accounts, :ssl_enabled
  end
end

class TenderloveMigration < ActiveRecord::Migration
  def change
    create_table(:horses) do |t|
      t.column :content, :text
      t.column :remind_at, :datetime
    end
  end
end

いかがでしょうか？
非常に簡潔に無駄なく説明されています。

ですが専門用語も多く、わかりやすさでいうと他にも良さそうな記事があるはずです...

ではなぜこういった読み難さを感じてしまうのでしょうか...？
例えば、以下のような原因が考えられると思います。

2-1. 情報量が多すぎる

利用者が多ければ多いほど、それぞれの疑問に応えるドキュメントが用意されています。
そこでは利用者すべての個別の使い方向けのサンプルを用意するのではなく、
曖昧さを排除した抽象度の高い原理や概念が説明されていることが必要とされます。

基本的に公式ドキュメントは情報を網羅的に出しているので、
情報が多すぎてパニックになってしまうことは多々あります。

確かに多いですが、新聞と同じで全部読む必要はないので、
必要なところだけ読んでいくようにしましょう。

その際、調べるためのキーワードがわかっていれば、
そのキーワードで検索することで公式ドキュメントの読むべき箇所を見つけられます。

キーワードがわからない、見つからないときは、用語集を探すといったアプローチが有効です。

2-2. 全体像を把握できていない

プログラミングに限らずまったく新しい分野を勉強するときには、効率のよい方法があります。

それは、最初に簡単な全体像をつかんでから、徐々に細部を理解していくというものです。
全体像をつかまないまま、闇雲に取り組んだところで、勉強の効果は薄く、時間の無駄になってしまいます。

ことドキュメントを読むと言うことに関していえば、その言語・フレームワーク・ライブラリが

なぜ作られたのか、何をするものなのか

をざっくりとでも知っていると理解が早くなります。

ex.) Ruby on Rails
設計哲学•••設定より規約(CoC), 同じ作業を繰り返さない(DRY)
特徴•••「MVCアーキテクチャ」に基づいて構築されたフレームワーク
できること•••Web開発向けのフレームワークとして設計されているため、Webアプリケーションを作るのに適している

2-3. 文字ばかりで無機質

どうしても膨大な情報を網羅しようとすると、
一つ一つの説明は必要最小限にならざるを得ないといった側面があります。

だからこそコードの記述例なども
とてもシンプルに、かつ無駄なく書かれているのですが、
それが逆に無機質で、読む際のとっつきにくさにつながっているようにも感じます

3. 公式ドキュメントを活用するメリット

では、あえて公式ドキュメントを活用することには
どう言ったメリットがあるのでしょうか？

3-1. 間違いがない一次情報に触れることができる

我々が学習しているプログラミング言語は必ず誰かによって作られています。

ある程度幅広く使用されている道具であれば通常、
それを作った人・組織自身によって公開されているドキュメントがあるはずです。

これが公式ドキュメントです。

つまり作者かもしくは作者の意図を知っている人
が公開しているため、
公式ドキュメントには常に「正しいこと」が書かれています。

多くの情報であふれている現代において、間違いがないという信頼性が担保されている点はやはり、まず初めに特筆するべき部分かなと思います。

3-2. 情報が網羅されている

Webで検索すると、ブログなどで多くの人がサンプルコードや解説記事を公開しています。
そうした情報は公式ドキュメントよりも読みやすいため、私もよく参考にします。

しかし、このような情報は
執筆した人の課題に対応するためのごく限られた範囲に制限されている
と言ったデメリットもあります。

それに対し公式ドキュメントには、
その言語に関する全般的な知識が過不足なくかつ体系的にまとまっています。

そう言った汎用性の高さが魅力の一つでもあります。

3-3. 分かりやすさの弊害

初学者の方はこういった抽象度の高いドキュメントを読み解くよりも、
自分と全く同じケースの課題を解決した「具体的な正解」を検索して見つけようとしてしまいます。

そのため、Qiitaや誰かのblog等で近いケースを見つけると、
原理や概念 を理解しないままコードを使おうとして、
うまく動作しなかったり、解釈が難しい複雑なコードを書いてしまいます。

そう言った場合、あとから振り返って
公式ドキュメントを読み解くことがゴールへの最短ルートだったということがよくあります。

3-4. 綺麗なコードが書けるようになる

公式ドキュメントに書かれてるコードは、とても綺麗で洗練されています。

そんなコードに普段から触れていれば、
(きっと)自然と綺麗なコードを書けるようになっていくでしょう。

4. どのように活用すればいいのか

以上を踏まえ、上手に公式ドキュメントを活用していくにはどのようにすればいいでしょうか...？

結論として

・まずは公式ドキュメントに目を通し、キーワードや不明点の核となる部分を掴む
　　　　　　　　　　　　　　　　
・必要に応じてQiita、技術ブログ等を参考にし、具体的なコードに落とし込んでいく

と言った流れが効果的なのではないかなと思います。

それぞれの良いとこ取りをできるような使い方ができたら理想ですね！

5. 最後に

ここまででちょっとでも
公式ドキュメントを読んでみようかな
と思って頂ければ嬉しいです。

少しずつでもいいのでドキュメントに目を通す頻度を増やし
ぜひ使いこなせるようになっていきましょう！

最後まで読んでいただきありがとうございました