目次
- 背景
- TL;DR
- 状況説明
- 公式ドキュメントを開いてみる
- ルール1 ドキュメントはインデントが深いほど具体的
- ルール2 ドキュメントは関連度順に書かれている
- 公式ドキュメントを読むためのTips
- まとめ
- PR
- 関連記事
背景
こんにちは。 かりんとうマニア(@karintozuki)です。
つよつよエンジニアのあるあるとして公式ドキュメント読めと言うのがあります。
私も読むようにしていますが、公式ドキュメントを読み始めたときはどのように読んでいいかわからず苦戦していました。
読めないから読まない、読まないからいつまで経っても読めるようにならない、という悪循環ですね。
なので、この記事では私が公式ドキュメントを読んでいるときに考えていることを言語化してみます。
TL;DR
はじめに結論です。以下の内容がなんとなく腹落ちする人はこの記事で言いたいことがすでにできていると思うので、読まなくても大丈夫と思います。これを読む代わりに公式ドキュメントでも読みましょう笑。
ルール１: ドキュメントはインデントが深いほど具体的、浅いほど概念的。
なので、理解できなかったら浅いインデントにもどって概念を勉強する
ルール２: ドキュメントは関連度順に並んでいる
なので、全ては読まずに最初の方に書かれている情報に集中する
それでは詳細を説明していきます。
状況説明
この記事では実際に私が公式ドキュメントを読む必要があった場面を例にします。
最近、業務でOpenSearchを使った際、分からないところがあったので公式ドキュメントを当たることにしました。
ちなみに例として挙げているだけなのでこの記事を読むのにOpenSearchの知識はいりません。実際、筆者もログの調査に使っただけで、全文検索のためのやつ、くらいざっくりした理解です。逆に言えばその程度の理解でも公式ドキュメントを読み始めて良い、ということですね。
OpenSearchはこんなダッシュボードがあるのですが、使い方がよくわかりませんでした。ひとまずのゴールはログを/api/users/{user id}というパターンで検索したかったので、ワイルドカードを使えるか調べることにしました。
(画像出典: https://docs.opensearch.org/docs/latest/dashboards/quickstart/)
解決したかった問い：OpenSearchでワイルドカードを使った検索はどうやるのか
公式ドキュメントを開いてみる
何か分からないことがあった際、普通にググりますよね。最近はAIに聞くことも多いですね。
筆者は検索にワイルドカードを使いたかったのでこう検索しました
🔎「OpenSearch ワイルドカード」
検索結果はこんな感じです。
ここで２番目のQiita記事を開きたくなる気持ちを抑えて公式を開きましょう。
実際のドキュメントはこちら
なんだこのJsonは🤯！？と思いましたか？
ここでブラウザバックしてしまう人がほとんどと思いますが、それはもったいないです。
ルール1 ドキュメントはインデントが深いほど具体的
ここでこの記事で一番だいじなアドバイスを紹介します。
「分からないときは目次を見る」です。
公式ドキュメントというのは、ただの文章ではなく階層化されたドキュメントです。
目次はこんなふうに階層構造になっていますよね。
そして、その階層は以下のルールに従っています。
- インデントが浅くなるほど概念的（技術の概念やなぜ？の説明）
- インデントが深くなるほど具体的（コードの具体例や使い方の説明）
公式ドキュメントをみて書いてあることが理解できないときは、そもそも前提となる概念を理解していないことが多いです。
なので目次上のその一段、もしくはもっと下のレベルにある概念の説明を見てみてください。
私見ですが、公式ドキュメントがとっつきづらいのは、Googleからたどり着くのはいつも最深部の超具体例で本当に理解すべき抽象度にたどり着けないからだと思います。
ドキュメント書く側からしたら最初に概念の説明をしているつもりなんでしょうが、ドキュメントを頭から読み進める人なんてあまりいないですからね😅
OpenSearchの例で確認してみましょう。
wildcardのページ周辺の目次は以下のようになっています。
1 | Query DSL ← ２レベル下 |
これを見て理解できる浅さまで戻りましょう。
筆者は現在のレベル（=wildcard）はもちろん１レベル下のTerm-level queriesと言われてもピンと来なかったので２レベル下のQuery DSLの浅さまで戻ることにしました。
OpenSaerchのドキュメントでは一番浅いレベルになりますが、まあ、何も知らないので妥当でしょう。
ルール2 ドキュメントは関連度順に書かれている
適切かな〜と思うレベルのページを開いたら実際に読んでいきますが、ここでふたつめの大事なポイントを紹介します。
それは「全部読もうとしない」です。
なぜならドキュメント内の情報は関連度順に並んでいるからです。
- 最初に書いてあることはみんなが必要とする情報（＝関連度が高い）
- 最後の方に書いてあることは多くの人には関係ないことなので読まなくても良い、
ということです。
全部読まなくていいと思うと少し気が楽になりませんか。
OpenSearchの例をみてみましょう。
実際のドキュメントはこちら
個人的な指標ですが、私はまず見出しを読んで、必要そうな見出しは最初の一行を読むみたいな感じですすめます。
以下の画像のハイライトがついた部分が私が注意を払うところです。
ほとんど読んでないですね😅。でもそれで大丈夫です。
その指標に従ってドキュメントを読んだ結果、得られた情報はこんな感じです。
1 | Query DSL: Jsonで検索クエリが書ける |
逆に、以下は見出しだけみて今は読まなくてもいいと判断した箇所です。こういった箇所は一行目すら読まなくても大丈夫です。
- Geographic and xy queries:場所で検索するときは必要そうですが、今は関係なさそうなので読まない
- Unicodeに関する注意:URL検索には関係なさそうなので読まない。もし日本語を検索するなら読んだほうが良いかもですね。
- Expensive Query: 関係なさそうなので読まない（よく見るとリストの中にwildcardがあるので後で読んだほうがいいかもですね）
こうして全文検索と完全一致ベースという２つの種類の検索があることがわかりました。
それを理解したあとだと、最初にみた目次のレイアウトも納得が行きますね。
1 | Query DSL ← 今見ているページ |
ワイルドカードを使うという発想からWildcardページを見るところから出発しましたが、ここで、単純にURLに何かのキーワードが含まれているログを探すだけなら全文検索のFull-textクエリが使えそうだなーと思いつきました。
公式ドキュメントを紐解いたおかげで当初は知りえなかったような仮説が立てられるようになりました。
実際この仮説は正しくて、このあと私はFull-text queryのページを見て具体例を確認し、無事に目的のログを発見することができました。
公式ドキュメントをあたったことで
- 他のもっといい方法を発見できた
- そもそも検索にどんな体系があるのか理解できた
- 公式ドキュメントのどこに何が書かれているか理解したので、次読むときはもっと早く読めるようになった
と良いことづくめです。
ここで最初に諦めてQiita記事を見ていたらWildcard検索はできるようになったかもしれませんが、これらのメリットは得られずじまいだったと思います。
公式ドキュメントを読むコツとメリットが少しは伝わったでしょうか。
公式ドキュメントを読むためのTips
先ほどまでは公式ドキュメントの説明でしたが、以下では具体的なTipsを紹介します。
理解できなかったら目次
これは前述したように階層構造を理解し、どこを読むべきか確認するためです。
目次を見ることで体系だった知識の構造が分かるようになります。
見出しを流し見する、一行目だけ読む
これも前述のとおりですが、本当に全部読まなくてもいい、と思うと気持ちが楽になります。
見出しの他にはサンプルコードなんかも見たほうが良いですね。
これに関連して、もし自分があまりその技術に馴染みがなければドキュメントの最初のページを読むのも結構役に立ちます。
大体プロジェクトの意義やら思想やらが書いてあるので。
とりあえず開く
公式ドキュメントは慣れというか勘所みたいなのがあります。コードを読むときも知っているフレームワークや同じようなプロジェクトだと早く読めるのと同じでドキュメントも慣れれば早く読めるようになります。
私はこの記事を書くまで言語化こそしませんでしたが、こういう勘所みたいなものを活用して公式ドキュメントを読んできました。
どんどん読んで慣れていきましょう。
英語を勉強する
これは言わずもがななんですが英語ができたほうが良いです。
メジャーなオープンソースだと翻訳があったりしますが、大体の公式ドキュメントはまだまだ翻訳されているものは少ないと思います。
もちろんAIの翻訳も精度が良くなっていますが、現状は英語が読めるに越したことはないと思います。
ちなみに公式ドキュメントを読むために英語を勉強したい方はこちらの記事もおすすめです。
英語を学びたいプログラマが知るべき一冊の本
番外編：逆に全部読む
これはサクッと課題を解決するためには全然役にたたないので番外編です。
いつも使っている技術について深く知りたいときに、全部読むなというアドバイスと完全に矛盾しますが、ドキュメントを全部読むのはとても効果的だそうです。
何人かのエンジニアがおすすめしているのを聞いたことがあるので、多分効果的なんだろうと思います。
私はまだ何かのドキュメントを全部読んだことはないので断言はできませんが、Laravelのドキュメントにはほぼ目を通したため、業務で使う際にかなり解像度が上がった実感がありました。
時間がある人は試してみてください。
まとめ
公式ドキュメントを読むときに私が考えていること、読むときのコツを記事にしてみました。
なかなかとっつきづらいと思いますが、すこしずつ理解できるようになって読むのが楽しくなってくるのでぜひ挑戦してみてください。
それじゃ今日はこの辺で。
PR
エンジニアならドメインのひとつやふたつ、持っておきたいですよね。ドメイン取得にはお名前ドットコムがおすすめです。
関連記事
こちらの記事もおすすめです。