公式ドキュメントは読まずに引く — 英語のまま調べる

公式ドキュメントの調べ方。開いた技術マニュアルと検索の虫眼鏡、索引の付箋。

公式ドキュメントは、最初から読むものではなく必要な場所を引くものです。manコマンドと、英語ドキュメントに共通する構造を押さえます。

前回: エラーは下から読む — メッセージの読み方と調べ方

この記事は英語の勉強の記事ではありません。 単語帳も文法も出てきません。

この記事の man は Ubuntu(VMの中)で打ちます。 Web のドキュメントの話は、Windows のブラウザでも構いません。

分からないことが出てきたとき、多くの人がやることは同じです。

検索して、日本語の個人ブログを上から順に開く。

自分もそうしていました。そして、こうなります。

1本目: 手順どおりにやったが、画面が違う
2本目: 同じ内容。たぶん1本目を写している
3本目: 3年前の記事。コマンドが今と違う
4本目: 「私も同じエラーが出ました」で終わっている
5本目: 解決しているが、なぜ直ったのか書いていない

1時間溶けます。 そして、同じことが公式ドキュメントには最初のページから書いてあった、ということが起きます。

なぜ公式を開かないのか。 理由はだいたいこの3つです。

避ける理由実際のところ
英語だから必要なのは英語力ではありません。 出てくる単語は限られていて、その表は下に載せます
長いから長いのは当たり前です。 全部読むものではないからです
どこを読めばいいか分からないここが本題です。 どのサイトも同じ形をしています

この記事の主題は「英語を読む技術」ではなく、「読む必要のある部分だけ読む技術」です。

対象レベル: PC入門 / 区分: 必修

目次

この記事でわかること

  • 公式ドキュメントは読むものではなく引くもので、辞書と同じだということ
  • 手元に一次情報があること(man)と、SYNOPSIS の [] ... | が何を意味するか
  • 公式サイトは Getting Started / Guide / Reference / API / Changelog に分かれていて、困ったときに読むのは Reference だということ
  • 日本語訳のドキュメントは古いことがあるので、英語版と日付を比べる必要があること
  • 動かなくなったときの一次情報は CHANGELOG だということ
  • AIの要約は、公式を開かずに信じてはいけないこと

この記事でやること

  1. man ls を開いて、SYNOPSIS の記号を読む
  2. man の中を / で検索して、q で出る
  3. --help と man を使い分ける
  4. Web の公式ドキュメントを開いて、5つの区画がどこにあるかを確かめる
  5. バージョン切り替えの場所を探す
  6. CHANGELOG を開いて、動かなくなった原因の探し方を確かめる

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
一次情報作った本人が書いた情報。公式ドキュメント・man・ソースコードがこれにあたる。ブログは二次情報
リファレンス(Reference)全部の機能を漏れなく並べた説明書。読み物ではなく、引くための表
CHANGELOG(変更履歴)そのソフトのバージョンごとに「何が変わったか」を並べたファイル。動かなくなったときに見る
deprecated(非推奨)「まだ動くが、そのうち消す」という印。新しく書くときは使わない
breaking change(破壊的変更)更新すると、今まで動いていたものが動かなくなる変更
IssuesGitHub 上の「困りごと掲示板」。同じ問題に他の人がすでに当たっていることが多い

公式ドキュメントは「読む」ものではなく「引く」もの

ここが一番大きな誤解でした。

自分は公式ドキュメントを教科書だと思っていました。だから「最初から読む → 3ページで飽きる → 二度と開かない」を繰り返していました。

公式ドキュメントは教科書ではなく、辞書です。

辞書を1ページ目から読む人はいません。 引きたい語だけ引いて、閉じます。ドキュメントも同じです。

教科書として読む(挫折する)辞書として引く(続く)
最初から順に読む今困っていることの語で検索する
全部理解しようとする今日使う1項目だけ分かればいい
読み終えてから手を動かす手を動かして、詰まってから開く
読み終わらないので開かなくなる1回3分で閉じるので、何度でも開ける

引くときに必要なのは、「何を引けばいいか」の言葉です。 これはエラーメッセージやコマンド名が教えてくれます。

手元に一次情報がある — man を引く

ネットを見る前に、まず手元を見ます。

Linux のコマンドには、そのコマンドを作った人が書いた説明書が最初から入っています。基本コマンドの回で名前だけ出した man です。

VM の中で打ちます。

bash
$ man ls

[スクリーンショット: 01_man_ls.png] man ls を実行して、NAME と SYNOPSIS が見えている画面を撮ってください。

SYNOPSIS の記号を読めるようにする

man を開くと、上のほうにこういう1行があります。ここが一番大事な行です。

SYNOPSIS
       ls [OPTION]... [FILE]...

この記号には意味があります。 意味を知らないと、ただの模様に見えます。

記号意味例の読み方
[ ]省略できる[OPTION] → オプションは付けなくてよい
...複数書ける[FILE]... → ファイルは何個並べてもよい
縦棒どれか1つを選ぶ-a と -b が縦棒で区切られていたら、どちらか一方
太字・そのままの文字そのとおりに打つls はこの綴りで打つ
大文字・斜体自分の値に置き換えるFILE は実際のファイル名に替える
{ }まとまり。省略はできない中を縦棒で区切ってあれば、そのどれかを必ず1つ書く

つまり ls [OPTION]... [FILE]... は、「ls は単体でも打てるし、オプションもファイルもいくつでも並べられる」と言っています。

この1行が読めるようになると、初めて使うコマンドでも打ち方が分かります。 使い方を検索する回数がはっきり減ります。

man の中の歩き方(これだけ覚える)

man は画面いっぱいに表示されて、そのままだと出られません。 自分は最初、ターミナルの窓ごと閉じていました。

操作何が起きるか
/ を押して語を打ち Enterその語を検索する(例: /--all)
n次の一致へ進む
N(大文字)前の一致へ戻る
Space1画面進む
b1画面戻る
g / G先頭へ / 末尾へ
q終わる。これだけは必ず覚える

man は「読む」画面ではなく「検索する」画面です。 開いたら、まず / を押します。

たとえば「ls で更新日時の新しい順に並べたい」なら、上から読むのではなく、こうします。

bash
$ man ls

そのあと /sort と打って Enter、n で次へ。該当箇所だけ読んで q で出ます。 30秒で終わります。

--help と man の使い分け

ほとんどのコマンドは、--help でも短い説明を出せます。

bash
$ ls --help

どちらを使うかは、探し物の大きさで決めます。

使う場面特徴
--helpオプションの綴りを思い出したいだけ速い。数十行。画面に流れて終わる
man意味・注意・書式・例まで知りたい詳しい。長い。検索して引く

先に --help、足りなければ man。 この順番で困ることはほぼありません。

man が無いときがある

入れたばかりの Ubuntu や、Docker のコンテナの中には man が入っていないことがあります。 man ls と打っても「そんなコマンドは無い」と言われます。

そのときはパッケージ管理の回でやったとおり、必要なものを入れます。

bash
$ sudo apt update
$ sudo apt install manpages man-db

もう1つ。tldr という道具があります。 man の長い説明ではなく、よく使う例だけを数行で出すものです。man の代わりにはなりませんが、「例だけ見たい」ときに速いので、名前だけ覚えておくと役に立ちます。

Web の公式ドキュメントは、どれも同じ形をしている

ここが分かると、初めて見るサイトでも迷わなくなります。

言語もライブラリもミドルウェアも、公式サイトの中身はだいたい同じ5つの区画でできています。名前が少し違うだけです。

区画よくある名前何が書いてあるかいつ開くか
入門Getting Started / Quickstart / Tutorial最初の1回だけの手順。最短で動かす道一番最初の1回だけ
手引きGuide / Guides / Learn / Handbookやりたいこと別の説明。「〜する方法」やり方の方針が分からないとき
リファレンスReference / Manual / Configuration全機能の一覧。読み物ではなく表困ったときはここ
APIAPI / API Reference関数・エンドポイント・引数と戻り値コードを書いている最中
変更履歴Changelog / Release Notes / What’s Newバージョンごとに何が変わったか急に動かなくなったとき

一番よくある失敗は、困ったときに Getting Started を最初から読み直すことです。

Getting Started には「うまくいく道」しか書いてありません。 うまくいっていない人が読んでも、書いていないのです。あなたが読むべきは Reference です。

具体的にはこうします。

  1. エラーメッセージや設定項目の名前を、そのまま公式サイト内の検索窓に入れる
  2. 出てきた Reference のページを開く
  3. その項目の説明・既定値・注意書きだけ読む
  4. 閉じる

検索エンジンで探すより、公式サイトの中の検索窓のほうが当たります。 外の検索は個人ブログを先に出しますが、サイト内検索は公式のページしか返さないからです。

バージョン切り替えを必ず確認する

ここで一度、痛い目を見ました。

nginx の設定を調べていて、公式に書いてあるとおりに書いたのに動かない。原因は、自分が入れている版より新しい版のドキュメントを読んでいたことでした。その項目は、自分の版にはまだ存在していませんでした。

多くの公式サイトには、バージョンを切り替える場所があります。

場所見た目
左上か右上のプルダウンv3.12 latest stable のような表示
URL の中/en/stable/ /latest/ /v2/ のような区切り
ページ上部の帯「これは開発版のドキュメントです」という警告

手元の版は、コマンドで確かめられます。

bash
$ nginx -v
$ node -v
$ python3 --version

latest や dev を読んだまま作業しない。 出てきた数字と、ドキュメントの版を合わせてから読みます。

[スクリーンショット: 02_docs_version.png] 公式ドキュメントのバージョン切り替え部分が写るように撮ってください。

英語のまま読むための、最小限

ここでも英語力の話はしません。

技術文書は、普通の英語とは違って、出てくる言い回しがほとんど決まっています。 小説ではないので、比喩も言い換えもありません。この20語が分かれば、大半のページは意味が取れます。

単語意味出てくる場面
required必須省略できない引数・設定
optional省略可書かなくてよい
default既定値何も書かなかったときの値
deprecated非推奨まだ動くが、いずれ消える
removed削除済みもう無い
breaking change破壊的変更更新すると動かなくなる
note補足読み飛ばしてよいことが多い
warning / caution警告飛ばすと事故る
see also関連項目目的のページが隣にあることが多い
example例困ったらここだけ見る
usage使い方・書式SYNOPSIS と同じ役割
argument / parameter引数コマンドや関数に渡す値
option / flagオプション-l のような指定
returns戻り値関数が返すもの
throws / raises例外を出す失敗したときの挙動
pathパスファイルの置き場所
enable / disable有効化 / 無効化設定の切り替え
override上書きする既定値を自分の値で置き換える
fallback代わりに使うもの本命が使えないとき
prerequisite前提条件これを飛ばすと動かない

逆に言えば、この20語以外は読めなくても困りません。 分からない単語は飛ばして、コードとオプション名だけ拾えば用は足ります。

翻訳をどう使うか

翻訳を使ってはいけない、とは言いません。使います。 ただし、訳してよい部分と、原文を見るべき部分があります。

部分翻訳理由
説明文・背景・注意書き訳してよい意味が取れれば十分
コード・コマンド・設定例原文を見る訳すと動かなくなる
オプション名・関数名・設定キー原文を見る訳語で検索しても出てこない
エラーメッセージ意味は訳す。打ち込むときは原文検索に使うのは原文

実際にやった失敗があります。 ページ全体をブラウザの翻訳機能で日本語にしたまま、コードブロックの中身をコピーしました。コード内の文字列まで日本語に変えられていて、動きませんでした。

コードブロックをコピーするときは、翻訳を切ってからにします。

日本語訳のドキュメントは、古いことがある

公式サイト自体に日本語版があることもあります。それでも、そのまま信じません。

翻訳は、原文が更新されたあとに遅れて追いつきます。 ひどいときは数年遅れています。「書いてあるとおりにしたのに動かない」の原因が、これだったことがあります。

確かめ方は単純です。

  1. 日本語ページの下のほうにある「最終更新日」を見る
  2. 同じページの英語版(URL の /ja/ を /en/ に替えるだけで開けることが多い)の日付を見る
  3. 日付が離れていたら、英語版を正とする

日本語版は「意味をつかむため」に読み、判断は英語版でする。 これで事故が減ります。

動かなくなったら、CHANGELOG を引く

昨日まで動いていたものが、今日動かない。 このとき読むべきは、ブログでも検索でもありません。

更新して壊れたときの一次情報は CHANGELOG です。

npm の回で出てきたバージョン番号の3つの数字と、ここが繋がります。

上がった場所呼び方意味
左(2.x.x → 3.0.0)メジャー壊れる変更が入っている。CHANGELOG を必ず読む
真ん中(2.3.x → 2.4.0)マイナー機能追加。壊れないはず
右(2.3.1 → 2.3.2)パッチ修正のみ

つまり、いま入っている版と、動いていたときの版の数字を比べれば、読むべき範囲が決まります。 全部読む必要はありません。

探し方はこの順です。

  1. 手元の版を確かめる(node -v など)
  2. 公式サイトの Changelog / Release Notes を開く
  3. 動いていた版から今の版までの間だけ見る
  4. Breaking Removed Deprecated の行だけ拾う

GitHub 上にあるプロジェクトなら、リポジトリの直下に CHANGELOG.md というファイルが置いてあることも多いです。Releases のページにも同じ内容が並びます。

最後の手段: ソースと Issues

ここまでやって、まだ分からないことがあります。 ドキュメントに書かれていない挙動です。

そのときの順番は、ソースより先に Issues です。

順番やること理由
1GitHub の Issues をエラーメッセージで検索する同じ問題に必ず誰かが先に当たっている
2閉じた Issue も検索対象に入れる解決済みのものにこそ答えがある
3ソースコードの該当箇所を見るドキュメントに無い既定値は、コードにしか無い

Issues を検索するときのコツは1つです。エラーメッセージの、環境依存の部分を消してから検索します。 自分のユーザー名やパスが混ざったままだと、1件も出ません。

(そのまま検索して0件)
Error: cannot open /home/hiro/server/config.json

(環境依存を消して検索して当たる)
Error: cannot open

ソースを読むのは、怖くありません。 全部読む必要は無く、grep の回と同じで、エラーメッセージの文字列でリポジトリ内を検索するだけです。そのメッセージを出している場所が、原因のすぐ近くにあります。

GitHub ではリポジトリのページで t キーを押すと、ファイル検索が開きます。「そのエラーを出しているコードは、必ずどこかに書いてある」という当たり前を、一度自分の目で見ておくと、以後ソースが怖くなくなります。

AIに要約させるとき

AIを開発に使う回と、同じ話がここにも出ます。

「この設定項目の意味は?」と聞けば、AIはすぐ答えます。 速いです。そして、間違っていても同じ口調で答えます。

AIの説明は「どこを読めばいいか」の案内として使い、内容は公式で確かめる。

具体的には、こう頼みます。

頼み方結果
❌「この設定の意味を教えて」もっともらしい説明が返る。確かめようがない
✅「公式ドキュメントのどのページに書いてあるか、リンクも出して」自分で開いて確かめられる
✅「この長いページの中で、この症状に関係する見出しだけ教えて」引く場所を絞る使い方。これが一番効く

返ってきたリンクが実在しないことがあります。 開いて404なら、その説明ごと疑います。開かずに信じない、これだけです。

AIが得意なのは「探す場所を絞ること」で、「正しさを保証すること」ではありません。 一次情報は、いつも公式のほうです。

やりすぎない

最後に、逆方向の注意です。

ここまで読むと「これからは全部公式を読もう」と思うかもしれません。それをやると、また止まります。

やりすぎ代わりにやること
❌ ドキュメントを最初から通読する✅ 今日詰まっている1項目だけ引く
❌ 全オプションを覚える✅ 必要になったときに man を開く。覚えない
❌ 分からない単語を全部調べる✅ 飛ばす。コードとオプション名だけ拾う
❌ 完全に理解してから手を動かす✅ 動かして、詰まってから引く

公式ドキュメントは、読み終えるものではありません。 何度も開いて、すぐ閉じるものです。

つまずいたところ

1. man から出られなくて、ターミナルを閉じていた

これが恥ずかしながら最初の壁でした。q を知らず、Ctrl を色々押して抜けられず、窓ごと閉じていました。q だけ先に覚えていれば、man を避けずに済んだはずです。

2. SYNOPSIS を模様だと思っていた

[OPTION]... の角括弧に意味があると思っていませんでした。「省略できる」「複数書ける」だと知った日から、初見のコマンドの打ち方が自分で分かるようになりました。 一番効いた知識です。

3. 困るたびに Getting Started に戻っていた

「基礎から分かっていないから詰まるのだ」と思い込んで、毎回入門ページを読み直していました。入門ページには、うまくいく道しか書いてありません。 詰まっている人が読んでも、そこに答えは無いのです。Reference に行くべきでした。

4. 日本語訳を読んで、書いてあるとおりにして動かなかった

原因は訳が古かったことでした。原文では、その設定はすでに deprecated になっていました。英語版の日付を見るまで、まさか訳が遅れているとは思っていませんでした。

5. ページごと翻訳したままコードをコピーした

コードブロックの中の文字列まで日本語になっていました。エラーの原因が自分の翻訳だと気づくまで、30分かかりました。

6. バージョンを合わせずに読んでいた

latest のドキュメントを読み、手元に存在しない項目を設定して、当然動きませんでした。「公式に書いてあるのに動かない」と思ったら、まず版を疑います。

まとめ

  • 公式ドキュメントは教科書ではなく辞書。 読むのではなく引く。最初から読まない
  • 個人ブログを10本読んでも解決しないことが、公式1ページで終わることは珍しくない
  • 避ける理由の本体は英語ではなく、「どこを読めばいいか分からない」ほう
  • 手元に一次情報がある。man はそのコマンドを作った人が書いた説明書
  • SYNOPSIS の [] は省略可、... は複数、| はどれか1つ、大文字は自分の値に置き換える
  • man は読む画面ではなく検索する画面。/ で検索、n で次、q で出る
  • 綴りの確認は --help、意味と注意は man。 man が無い環境では入れる。例だけ見たいなら tldr もある
  • どの公式サイトも同じ5区画。 入門 / 手引き / Reference / API / Changelog
  • 困ったときに Getting Started を読み直さない。 入門にはうまくいく道しか書いていない
  • 検索エンジンより、公式サイト内の検索窓のほうが当たる
  • バージョン切り替えを必ず確認する。 latest を読んだまま作業しない
  • 技術文書に出る単語は限られている。 required default deprecated breaking change など20語で足りる
  • 説明文は訳してよい。コード・オプション名・設定キーは原文を見る
  • ページ翻訳したままコードをコピーしない。 文字列まで訳されて動かなくなる
  • 日本語訳は古いことがある。 英語版と最終更新日を比べて、離れていたら英語版を正とする
  • 動かなくなったときの一次情報は CHANGELOG。 メジャーが上がっていたら必ず読む
  • 読むのは「動いていた版から今の版まで」だけ。 Breaking Removed Deprecated の行を拾う
  • 分からないときは、ソースより先に Issues。 エラーメッセージから環境依存の部分を消して検索する
  • ソースは全部読まない。 エラーメッセージの文字列でリポジトリ内を検索すれば、出している場所に着く
  • AIの要約は「どこを読むか」の案内。 リンクを出させて、自分で開いて確かめる。開かずに信じない
  • やりすぎない。全部読まない。今日困っていることだけ引く

参考リンク


次に読む

この記事は 【第0段階】作業場所を作る の 18 / 18 本目です。

記事
← 前の記事エラーは下から読む — メッセージの読み方と調べ方
→ 次の記事Linuxにドライブレターは無い — ファイルの置き場所の考え方

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

公式ドキュメントの引き方は roadmap.sh の項目ではないが、全段階で使う土台。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次