背景
こんにちは。 かりんとうマニア(@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のページ周辺の目次は以下のようになっています。
Query DSL ← ２レベル下
│
├── Query and filter context
│
├── Term-level and full-text queries compared
│
├── Term-level queries ← １レベル下
│ │
│ ├── Exists
│ │
│ ├── Fuzzy
│ │
│ ├── ...
│ │
│ └── Wildcard ← 現在地
│
└── Full-text queries
これを見て理解できる浅さまで戻りましょう。
筆者は現在のレベル（=wildcard）はもちろん１レベル下のTerm-level queriesと言われてもピンと来なかったので２レベル下のQuery DSLの浅さまで戻ることにしました。
OpenSaerchのドキュメントでは一番浅いレベルになりますが、まあ、何も知らないので妥当でしょう。
分かるレベル（もしくはもっとも浅いレベル）まで容赦なく戻りましょう。
長期的にはそちらのほうが早いですから。
ルール2 ドキュメントは関連度順に書かれている
適切かな〜と思うレベルのページを開いたら実際に読んでいきますが、ここでふたつめの大事なポイントを紹介します。
それは「全部読もうとしない」です。
なぜならドキュメント内の情報は関連度順に並んでいるからです。
- 最初に書いてあることはみんなが必要とする情報（＝関連度が高い）
- 最後の方に書いてあることは多くの人には関係ないことなので読まなくても良い、
ということです。
関連度の高い情報だけ読み、ほかは読み飛ばしましょう。
全部読まなくていいと思うと少し気が楽になりませんか。
OpenSearchの例をみてみましょう。
実際のドキュメントはこちら
個人的な指標ですが、私はまず見出しを読んで、必要そうな見出しは最初の一行を読むみたいな感じですすめます。
以下の画像のハイライトがついた部分が私が注意を払うところです。
ほとんど読んでないですね😅。でもそれで大丈夫です。
その指標に従ってドキュメントを読んだ結果、得られた情報はこんな感じです。
Query DSL: Jsonで検索クエリが書ける
│
├── Leaf query: 指定されたフィールドに対するクエリ
│ │
│ ├── Full-text query: 全文検索をつかったクエリ
│ │
│ └── Term level query: 全文検索エンジンを使わない完全一致がベースのクエリ。
│ wildcardはこのタイプであることに気をつける。
│
└── Compound query: 複数のLeaf queryをまとめられる
逆に、以下は見出しだけみて今は読まなくてもいいと判断した箇所です。こういった箇所は一行目すら読まなくても大丈夫です。
- Geographic and xy queries:場所で検索するときは必要そうですが、今は関係なさそうなので読まない
- Unicodeに関する注意:URL検索には関係なさそうなので読まない。もし日本語を検索するなら読んだほうが良いかもですね。
- Expensive Query: 関係なさそうなので読まない（よく見るとリストの中にwildcardがあるので後で読んだほうがいいかもですね）
こうして全文検索と完全一致ベースという２つの種類の検索があることがわかりました。
それを理解したあとだと、最初にみた目次のレイアウトも納得が行きますね。
Query DSL ← 今見ているページ
│
├── Term-level and full-text queries compared: ２種類の検索の違い
│
├── Term-level queries: 完全一致ベースの検索
│ │
│ ├── Exists
│ │
│ ├── ...
│ │
│ └── Wildcard: ワイルドカード
│
└── Full-text queries: 全文検索
ワイルドカードを使うという発想からWildcardページを見るところから出発しましたが、ここで、単純にURLに何かのキーワードが含まれているログを探すだけなら全文検索のFull-textクエリが使えそうだなーと思いつきました。
公式ドキュメントを紐解いたおかげで当初は知りえなかったような仮説が立てられるようになりました。
実際この仮説は正しくて、このあと私はFull-text queryのページを見て具体例を確認し、無事に目的のログを発見することができました。
公式ドキュメントをあたったことで
- 他のもっといい方法を発見できた
- そもそも検索にどんな体系があるのか理解できた
- 公式ドキュメントのどこに何が書かれているか理解したので、次読むときはもっと早く読めるようになった
と良いことづくめです。
ここで最初に諦めてQiita記事を見ていたらWildcard検索はできるようになったかもしれませんが、これらのメリットは得られずじまいだったと思います。
公式ドキュメントを読むコツとメリットが少しは伝わったでしょうか。
まとめ
公式ドキュメントを読むときに私が考えていること、読むときのコツを記事にしてみました。
また実際に公式ドキュメントを読むことのメリットというかパワーみたいなのも伝えられていたら幸いです。直接的な知識だけでなく、体系だった周辺の知識も吸収できるのは良いですよね。
最初はとっつきづらいと思いますが、すこしずつ理解できるようになって読むのが楽しくなってくるので、ぜひ挑戦してみてください。
また、個人ブログのほうでは第二部として公式ドキュメントを読むときのTipsも紹介していますので良ければ読んでみてください。
個人ブログ版
それじゃ今日はこの辺で。