公式ドキュメントは、最初から読むものではなく必要な場所を引くものです。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の要約は、公式を開かずに信じてはいけないこと
この記事でやること
man lsを開いて、SYNOPSISの記号を読むmanの中を/で検索して、qで出る--helpとmanを使い分ける- Web の公式ドキュメントを開いて、5つの区画がどこにあるかを確かめる
- バージョン切り替えの場所を探す
- CHANGELOG を開いて、動かなくなった原因の探し方を確かめる
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 一次情報 | 作った本人が書いた情報。公式ドキュメント・man・ソースコードがこれにあたる。ブログは二次情報 |
| リファレンス(Reference) | 全部の機能を漏れなく並べた説明書。読み物ではなく、引くための表 |
| CHANGELOG(変更履歴) | そのソフトのバージョンごとに「何が変わったか」を並べたファイル。動かなくなったときに見る |
| deprecated(非推奨) | 「まだ動くが、そのうち消す」という印。新しく書くときは使わない |
| breaking change(破壊的変更) | 更新すると、今まで動いていたものが動かなくなる変更 |
| Issues | GitHub 上の「困りごと掲示板」。同じ問題に他の人がすでに当たっていることが多い |
公式ドキュメントは「読む」ものではなく「引く」もの
ここが一番大きな誤解でした。
自分は公式ドキュメントを教科書だと思っていました。だから「最初から読む → 3ページで飽きる → 二度と開かない」を繰り返していました。
公式ドキュメントは教科書ではなく、辞書です。
辞書を1ページ目から読む人はいません。 引きたい語だけ引いて、閉じます。ドキュメントも同じです。
| 教科書として読む(挫折する) | 辞書として引く(続く) |
|---|---|
| 最初から順に読む | 今困っていることの語で検索する |
| 全部理解しようとする | 今日使う1項目だけ分かればいい |
| 読み終えてから手を動かす | 手を動かして、詰まってから開く |
| 読み終わらないので開かなくなる | 1回3分で閉じるので、何度でも開ける |
引くときに必要なのは、「何を引けばいいか」の言葉です。 これはエラーメッセージやコマンド名が教えてくれます。
手元に一次情報がある — man を引く
ネットを見る前に、まず手元を見ます。
Linux のコマンドには、そのコマンドを作った人が書いた説明書が最初から入っています。基本コマンドの回で名前だけ出した man です。
VM の中で打ちます。
[スクリーンショット: 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(大文字) | 前の一致へ戻る |
Space | 1画面進む |
b | 1画面戻る |
g / G | 先頭へ / 末尾へ |
q | 終わる。これだけは必ず覚える |
manは「読む」画面ではなく「検索する」画面です。 開いたら、まず/を押します。
たとえば「ls で更新日時の新しい順に並べたい」なら、上から読むのではなく、こうします。
そのあと /sort と打って Enter、n で次へ。該当箇所だけ読んで q で出ます。 30秒で終わります。
--help と man の使い分け
ほとんどのコマンドは、--help でも短い説明を出せます。
どちらを使うかは、探し物の大きさで決めます。
| 使う場面 | 特徴 | |
|---|---|---|
--help | オプションの綴りを思い出したいだけ | 速い。数十行。画面に流れて終わる |
man | 意味・注意・書式・例まで知りたい | 詳しい。長い。検索して引く |
先に --help、足りなければ man。 この順番で困ることはほぼありません。
man が無いときがある
入れたばかりの Ubuntu や、Docker のコンテナの中には man が入っていないことがあります。 man ls と打っても「そんなコマンドは無い」と言われます。
そのときはパッケージ管理の回でやったとおり、必要なものを入れます。
もう1つ。tldr という道具があります。 man の長い説明ではなく、よく使う例だけを数行で出すものです。man の代わりにはなりませんが、「例だけ見たい」ときに速いので、名前だけ覚えておくと役に立ちます。
Web の公式ドキュメントは、どれも同じ形をしている
ここが分かると、初めて見るサイトでも迷わなくなります。
言語もライブラリもミドルウェアも、公式サイトの中身はだいたい同じ5つの区画でできています。名前が少し違うだけです。
| 区画 | よくある名前 | 何が書いてあるか | いつ開くか |
|---|---|---|---|
| 入門 | Getting Started / Quickstart / Tutorial | 最初の1回だけの手順。最短で動かす道 | 一番最初の1回だけ |
| 手引き | Guide / Guides / Learn / Handbook | やりたいこと別の説明。「〜する方法」 | やり方の方針が分からないとき |
| リファレンス | Reference / Manual / Configuration | 全機能の一覧。読み物ではなく表 | 困ったときはここ |
| API | API / API Reference | 関数・エンドポイント・引数と戻り値 | コードを書いている最中 |
| 変更履歴 | Changelog / Release Notes / What’s New | バージョンごとに何が変わったか | 急に動かなくなったとき |
一番よくある失敗は、困ったときに Getting Started を最初から読み直すことです。
Getting Started には「うまくいく道」しか書いてありません。 うまくいっていない人が読んでも、書いていないのです。あなたが読むべきは Reference です。
具体的にはこうします。
- エラーメッセージや設定項目の名前を、そのまま公式サイト内の検索窓に入れる
- 出てきた Reference のページを開く
- その項目の説明・既定値・注意書きだけ読む
- 閉じる
検索エンジンで探すより、公式サイトの中の検索窓のほうが当たります。 外の検索は個人ブログを先に出しますが、サイト内検索は公式のページしか返さないからです。
バージョン切り替えを必ず確認する
ここで一度、痛い目を見ました。
nginx の設定を調べていて、公式に書いてあるとおりに書いたのに動かない。原因は、自分が入れている版より新しい版のドキュメントを読んでいたことでした。その項目は、自分の版にはまだ存在していませんでした。
多くの公式サイトには、バージョンを切り替える場所があります。
| 場所 | 見た目 |
|---|---|
| 左上か右上のプルダウン | v3.12 latest stable のような表示 |
| URL の中 | /en/stable/ /latest/ /v2/ のような区切り |
| ページ上部の帯 | 「これは開発版のドキュメントです」という警告 |
手元の版は、コマンドで確かめられます。
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語以外は読めなくても困りません。 分からない単語は飛ばして、コードとオプション名だけ拾えば用は足ります。
翻訳をどう使うか
翻訳を使ってはいけない、とは言いません。使います。 ただし、訳してよい部分と、原文を見るべき部分があります。
| 部分 | 翻訳 | 理由 |
|---|---|---|
| 説明文・背景・注意書き | 訳してよい | 意味が取れれば十分 |
| コード・コマンド・設定例 | 原文を見る | 訳すと動かなくなる |
| オプション名・関数名・設定キー | 原文を見る | 訳語で検索しても出てこない |
| エラーメッセージ | 意味は訳す。打ち込むときは原文 | 検索に使うのは原文 |
実際にやった失敗があります。 ページ全体をブラウザの翻訳機能で日本語にしたまま、コードブロックの中身をコピーしました。コード内の文字列まで日本語に変えられていて、動きませんでした。
コードブロックをコピーするときは、翻訳を切ってからにします。
日本語訳のドキュメントは、古いことがある
公式サイト自体に日本語版があることもあります。それでも、そのまま信じません。
翻訳は、原文が更新されたあとに遅れて追いつきます。 ひどいときは数年遅れています。「書いてあるとおりにしたのに動かない」の原因が、これだったことがあります。
確かめ方は単純です。
- 日本語ページの下のほうにある「最終更新日」を見る
- 同じページの英語版(URL の
/ja/を/en/に替えるだけで開けることが多い)の日付を見る - 日付が離れていたら、英語版を正とする
日本語版は「意味をつかむため」に読み、判断は英語版でする。 これで事故が減ります。
動かなくなったら、CHANGELOG を引く
昨日まで動いていたものが、今日動かない。 このとき読むべきは、ブログでも検索でもありません。
更新して壊れたときの一次情報は CHANGELOG です。
npm の回で出てきたバージョン番号の3つの数字と、ここが繋がります。
| 上がった場所 | 呼び方 | 意味 |
|---|---|---|
左(2.x.x → 3.0.0) | メジャー | 壊れる変更が入っている。CHANGELOG を必ず読む |
真ん中(2.3.x → 2.4.0) | マイナー | 機能追加。壊れないはず |
右(2.3.1 → 2.3.2) | パッチ | 修正のみ |
つまり、いま入っている版と、動いていたときの版の数字を比べれば、読むべき範囲が決まります。 全部読む必要はありません。
探し方はこの順です。
- 手元の版を確かめる(
node -vなど) - 公式サイトの Changelog / Release Notes を開く
- 動いていた版から今の版までの間だけ見る
BreakingRemovedDeprecatedの行だけ拾う
GitHub 上にあるプロジェクトなら、リポジトリの直下に CHANGELOG.md というファイルが置いてあることも多いです。Releases のページにも同じ内容が並びます。
最後の手段: ソースと Issues
ここまでやって、まだ分からないことがあります。 ドキュメントに書かれていない挙動です。
そのときの順番は、ソースより先に Issues です。
| 順番 | やること | 理由 |
|---|---|---|
| 1 | GitHub の 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を読んだまま作業しない - 技術文書に出る単語は限られている。
requireddefaultdeprecatedbreaking changeなど20語で足りる - 説明文は訳してよい。コード・オプション名・設定キーは原文を見る
- ページ翻訳したままコードをコピーしない。 文字列まで訳されて動かなくなる
- 日本語訳は古いことがある。 英語版と最終更新日を比べて、離れていたら英語版を正とする
- 動かなくなったときの一次情報は CHANGELOG。 メジャーが上がっていたら必ず読む
- 読むのは「動いていた版から今の版まで」だけ。
BreakingRemovedDeprecatedの行を拾う - 分からないときは、ソースより先に Issues。 エラーメッセージから環境依存の部分を消して検索する
- ソースは全部読まない。 エラーメッセージの文字列でリポジトリ内を検索すれば、出している場所に着く
- AIの要約は「どこを読むか」の案内。 リンクを出させて、自分で開いて確かめる。開かずに信じない
- やりすぎない。全部読まない。今日困っていることだけ引く
参考リンク
- roadmap.sh
- man-pages プロジェクト(Linux の man の本体)
- man7.org — man(1) のマニュアル
- man7.org — ls(1) のマニュアル
- GNU coreutils 公式マニュアル
- tldr pages 公式サイト
- Ubuntu Server 公式ドキュメント
- nginx 公式ドキュメント
- Node.js 公式 API リファレンス
- Python 公式ドキュメント
- MDN Web Docs(日本語)
- Git 公式ドキュメント
- セマンティック バージョニング(日本語)
- Keep a Changelog
- GitHub 公式ドキュメント — コードを検索する
次に読む
この記事は 【第0段階】作業場所を作る の 18 / 18 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
公式ドキュメントの引き方は roadmap.sh の項目ではないが、全段階で使う土台。

コメント