はじめに
「公式ドキュメントを読め（※RTFM）」
※Read The Fucking Manual
エンジニアとして仕事、活動をしていたら誰もが聞く言葉ではないでしょうか。
かくいう私も言われたことがあります。
皆さんはどうでしょう。
公式ドキュメント、普段から読まれてますでしょうか。
実際、私はまだまだ公式ドキュメントの確認をサボりがち。
最近はAIに聞くことも増えています。かなり怠惰ですね・・・これは良くない怠惰。
AIに甘えながらも、「公式ドキュメントが読めない」のと「公式ドキュメントも読めるけど、AIに聞く」のとではかなりの違いがあるのではないかと危機感を感じています。
「え、まだ公式ドキュメント読まないの？」と言われないためにも、
今回は公式ドキュメントを読むべき理由と、なぜ苦手意識が生まれてしまうのかを考えていきます。
そして最後は、その対策も模索して公式ドキュメントと仲良くなることを目指します。
なぜ公式ドキュメントを読むべきなのか
1. 「信頼できる唯一の情報源（SSoT）」だから
SSoTとは
信頼できる唯一の情報源 (英語: single source of truth、SSOT) とは、情報システムの設計と理論においては、すべてのデータが1か所でのみ作成、あるいは編集されるように、情報モデルと関連するデータスキーマとを構造化する方法である。データへのリンクで可能なものは参照のみである。プライマリ以外の他の場所のすべてのデータは、プライマリの「信頼できる情報源」の場所を参照するだけであり、プライマリのデータが更新された場合、どこかで重複したり失われたりすることなく、システム全体に伝播される。
引用: Wikipedia
公式ドキュメントは一次情報でありSSoTでもあります。
最新情報が載っていて、しかも最も信頼できる情報源。
その信頼できる情報源を参照することは以下のメリットがあります。
- 古い情報を見て、無駄な時間を過ごさずに済む
- 誤った情報を広めるリスクが減る
- 何かあればドキュメントを読めばいいので最新情報を探す手間が減る
慣れるまでは億劫な公式ドキュメントも、慣れてしまえば安心して手早く確認できる便利な情報源となることでしょう。何よりも安心して情報をインプットできるのは、アウトプットが必須のエンジニアにとっては心強いと言えます。
2. 「How」ではなく「Why」がわかるから
コピペ実装では「どう書くか（How）」しか解決しません。
しかし公式ドキュメントには、設計思想や「なぜその機能が存在するのか（Why）」が書かれています。
設計思想や一つ一つのふるまいを理解することで、実装上の破綻を回避したり、問題解決における応用力が向上するはずです。
「カーゴ・カルト・プログラミング（意味もわからず儀式的にコードを書くこと）」から脱却するためにも、公式ドキュメントは力になってくれることでしょう。
3. チームの「基準」になるから
エンジニアとして働く方の多くは、チームとして複数人で開発していると思います。
その際、必要となってくるのは基準となるルールや方針です。
コードレビューで「なぜこの書き方？」と聞かれた時、チーム全員が公式ドキュメントを基準にしていれば議論がスムーズになります。「公式ドキュメントではこれを推奨しています」「こう書かれています」と伝えれば、それに従うだけですから。
独自ルールではなく、世界標準（Standard）に合わせることで、技術的負債を減らし、新しく入ったメンバーも学習しやすくなるのはチームとしても嬉しいメリットです。
なぜ公式ドキュメントは「あんなに読みづらい」のか？
ここからは逆に公式ドキュメントを読みたくない人の立場に立って考えてみようと思います。
1. 情報量に混乱しやすい（認知負荷）
多くのドキュメントは「網羅性」を重視して書かれています。欲しい情報に対して、いらない情報量が圧倒的に多いです。公式ドキュメントに読みなれた方は、「欲しい情報はここにありそうだな」とアタリをつけて探すことができると思います。
ですが読みなれてない方は、どこに何があるかもわからないまま彷徨ってしまったり、上から順に本を読むように調べてしまう方もいると思います。
そのうち情報量に圧倒されて、混乱し、疲れて苦手意識がついてしまうのかもしれません。
私も正直、それには身に覚えがあります・・・
2. 言語の壁がある
公式ドキュメントの原文は英語であることがほとんどです。
中には翻訳されているものもありますが、基本的には英語で書かれています。
翻訳されているとはいえ、読みやすいかと言われるとそうではないと思います。
原文そのままで読める方はすんなり入ってくるのかもしれません。
ですが英語が不得意な方、翻訳が必要な方にとっては、どうしても言語の壁を感じざるを得ないでしょう。
実際、私もまだまだ翻訳に頼りながら公式ドキュメントを読んでいます。
3. ドキュメント自体、そもそも読みづらいことも
全ての公式ドキュメントが良質とは限りません。
チュートリアル（学習）とリファレンス（仕様書）がごちゃ混ぜになっていたり、
文章や構造自体が親切とは言えないパターンもあります。
よく使用される主要な言語の公式ドキュメントは支障がないかもしれませんが、
世界的にもまだ主流ではないマイナーな技術の場合、苦労することもあるでしょう。
公式ドキュメントと仲良くなろう
ここまで公式ドキュメントを読むべき理由と、読みづらい理由をまとめてみました。
結論、やっぱりエンジニアは公式ドキュメントを読めるべきであると感じます。
読みづらい理由は考えられても、「読まなくていい理由」はなかなか思いつきません。
読むことを前提として、読みづらい理由から対策を行うべきだと思います。
なのでここからは「公式ドキュメントと友達」になる近道を考えます。
1. 全てを読もうとしない
まず、手軽に試せる方法は読み方の意識を変えることです。
小説のように1から順に読んでいくのではなく、
辞書のように必要な情報が記されたピンポイントの場所を探す。
本屋に足を運んでまず目次から読むように、公式ドキュメントもまずは目次から読んでみる。
そして自分の欲しい情報がありそうな場所を見つけて、そこから読み進める。
全体から詳細に入っていくのが公式ドキュメントと仲良くなるコツではないでしょうか。
まず自分が欲しい情報はどの領域に含まれるのか。
そこを踏まえて、公式ドキュメントを部分的に読んでみましょう。
2. Diataxisフレームワークに当てはめてみる
調べてみて知ったのですが、ドキュメントにもフレームワークがあるそうです。
その名もDiataxis
ドキュメントを大まかに４つのセクションに分ける考え方で、多くのドキュメントに採用された実績があるとのこと。自分がどんな情報を知りたいかを明確にし、適したセクションを探してみるといいかもしれません。
| セクション名 | 目的 | 日本語でのイメージ | いつ読むべき？ |
|---|---|---|---|
| TUTORIALS | 手を動かして体験する | 入門・チュートリアル | 初めてその技術に触れる時 |
| HOW-TO GUIDES | 実装例を見る | 解説書・ガイド | 目的があって実現手段が知りたい時 |
| REFERENCE | 機能の詳細を調べる | 辞書・仕様書 | 引数や戻り値など、細かい仕様を知りたい時 |
| EXPLANATION | 仕組みや概念を学ぶ | より詳細なドキュメント | システムの理解を深めたい時 |
3. 「コード・ファースト」で読む（英語を後回しにする）
英語が苦手な人におすすめなテクニックは、「本文（英語）より先にコードブロックを読む」ことです。
-
コードを見る： プログラミング言語は万国共通です。コードを見れば、何をしているか大体予想がつきます。
-
パラメーターを見る： 変数名や引数名（timeout, color, user_idなど）から機能を推測します。
-
英語は答え合わせ： コードを見て「多分こういうことかな？」と仮説を立ててから、その確認のために前後の英語を読みます。
これだけで、英文解読の負担が7〜8割減らせます。
4. 検索テクニックを活用する
サイト内検索バーが使いにくい場合や、知りたい情報にたどり着けない場合は、Google検索のコマンドを活用します。
-
site:検索を使う 例えば、Pythonの公式ドキュメント（docs.python.org）の中で json について調べたい場合、Googleの検索窓にこう入力します。site:docs.python.org json
これにより、QiitaやZennなどの解説記事（二次情報）を除外し、公式ドキュメントの中から直接該当ページを見つけ出せます。
- ページ内検索（Ctrl + F / Cmd + F） 長いページを開いたら、すぐに Ctrl + F を押し、知りたいキーワード（例：
error,limit,config）を入力して該当箇所へジャンプします。
5. いっそ英語を勉強する
結局はこれが長期的にみると一番なのかもしれません。
これまでのテクニックを使って乗り切りつつ、空いた時間で英語とリーディングの学習をする。
すらすらと英語を読めるようにするのが最も効果的な対策かもしれませんね。
やはり怠惰を極めるには相応の努力が必要・・・怠けるために頑張る。
それをするしかないようです。
まとめ
いかがだったでしょうか。
エンジニアには公式ドキュメントを読みなれた人や、苦手な人、もはや読まない人と色んなタイプがいると思います。目的志向の方なら「目的が達成できればAIに聞いて解決するので、公式ドキュメントなんて読まなくていい」という方もいるかもしれませんね。
ですが現状、まだまだ公式ドキュメントを読んだ方がよさそうです。
慣れない人にとっては決して読みやすいとは言えない公式ドキュメントですが、
この記事が少しでも「公式ドキュメントと仲良くなる」きっかけになれば幸いです。
最後まで読んでいただきありがとうございました！
参考文献
Diátaxis というドキュメントフレームワークについて
Diataxisという思考ツールとしてのフレームワーク
site: 検索演算子