開発者と公式ドキュメントの間にある不自然な距離感

開発者と公式ドキュメントの間には常に不自然な距離感がある

「ドキュメントが読めないのは自分のスキルが足りないから？」私はかなり長い間、こう信じて生きてきました。

1. 「自分だけが理解できないように思えた」

フレームワーク、ライブラリ、REST API、クラウドサービス… 今ではほとんどのものが公式ドキュメントでしっかりと整備されています。問題は… それを自分がよく理解できないということです。

初心者の頃はこう考えていました。

「あ…まだスキルが足りないんだろう。もっと勉強すれば、いつかこのドキュメントもスムーズに読めるはず…」

だから一生懸命読んでみます。ところが：

原理がよくわからない
どこまでが概念で、どこからが実際の使用例か混乱する
内容は読んだはずなのに、コードを書こうとすると手が動かない
ドキュメントの量がなぜこんなに多いのか…

今では少なくとも 「初心者」という言葉を聞くことがほとんどない 開発者になったと思います。それでも新しいライブラリのドキュメントを見ると、心の中でこう言います。

「わあ…また始まるのか…」

スキル不足だけではないことは、今では分かっています。

2. ドキュメントは通常「作成者の視点」で書かれている

ドキュメントが難しい最大の理由は、ほとんどの公式ドキュメントが 「作成者の頭の中の構造」 を基準に書かれているからだと感じます。

その人はすでに
内部構造を知っている
なぜこの設計にしたのかを知っている
どんな制約があるかを知っている
この関数がどこでどのように呼び出されるかを知っている
だからドキュメントには主にこういうことが書かれます。
このメソッドはこういうパラメータを受け取る
この型を返す
このケースでは例外を投げる
これでこういうことができる…

問題は、私たちはそのプログラムを作った人ではないということです。

私たちが知りたいのは、通常こういうことです。

「これを どこから 始めればいい？」
「今直面している この問題 を解決するには、ドキュメントの どの部分 を見るべき？」
「このオプションは実際に どんな状況 で必要なのか？」
「このコード一行は実際にいつ呼び出されるのか？」

しかしドキュメントはこう言います。

「このオプションは foo という動作と bar という戦略を使って baz を実行します。」

…このくらいで、まず例を動かしてみたくなります。

3. 「自分のドキュメントも結局他人には難しい」

面白いのは、私も自分が作った API やライブラリについてドキュメントを書いていることです。それでも同じく 「作成者の視点」 で書いてしまいます。

「この関数はこういう機能を持つ…」
「このエンドポイントはこういう引数を受け取る…」
「こういう形の JSON を返す…」
「成功/失敗時のレスポンスはこうなる…」

そして考えます。

「この程度でかなり親切なドキュメントではないか？」

しかしチームメンバーの反応は大体こうです。

「まず口頭で一度説明してくれない？」
「ドキュメントはあるけど…質問したほうが早いと思う」

さらに面白いのは、自分が以前書いたドキュメントを自分が読めないこともある という点です。

昔作った API を再び使おうと古いドキュメントを開くと：

「あ…これ、私が書いたものだよね？なんでこんな説明を変にしてしまったんだ…？」

その時に気づきました。

ドキュメントを書いたからといって、すぐに「よく理解できるドキュメント」になるわけではない。
私がよく読めない公式ドキュメントを非難する資格は…実際はほとんどない。 😅

4. 公式ドキュメントは「最初は読めない」ことが当然

プロジェクトごとに必ず使うライブラリやパッケージが一つはあります。それはブラウザにタブで固定して、作業中にずっと開いておくようなドキュメントです。

しかし不思議なことがあります。

最初に読むときは
「一体何を言っているんだ…」と思う文がある
プロジェクトの終盤で再び読むと
「あ、これがそういう意味だったんだ…」と理解できる

そしてよくこう考えます。

「いや、ここにこう書いてあったのに？以前読んだはずなのに、当時は意味が分からなかった…」

なぜそうなるのでしょうか？

ドキュメントの内容を理解するには、 ある程度書いた経験と文脈 が必要です。
しかしその経験を積むには まずはざっくりでもドキュメントを見て何かを作ってみる 必要があります。

つまり、ドキュメントを理解するためにはドキュメントを理解した状態が必要 という奇妙な循環構造に陥りやすいのです。

だから私は今こう考えます。

「公式ドキュメントは一度で理解できるものではない。数回プロジェクトを通じて再度見ることで初めて読める ドキュメントだ。」

つまり、最初に読めないのは当然です。あなたが不足しているわけではなく、元々その構造 なのです。

5. 非英語圏の開発者は難易度+2

ここで私たちは 非英語圏の開発者 というハンディキャップも持っています。

英語の文章自体は読めます。
技術用語も今ではかなり慣れています。
本も好きで、文章を読むのも好きなので「読解力が足りない」と感じることはありません。

それでも公式ドキュメントを読むと奇妙に 脳がより早く疲れる という感覚が湧きます。

これはスキル不足ではなく、

英語という言語自体に継続的に「認知コスト」がかかっている
さらに
新しい概念
未知の API 設計
抽象的な例題コードが一度に押し込まれる

という理由です。

つまり、他人より同じ内容を理解するために エネルギー消費が大きいゲームをしている ので、当然より疲れやすく、より難しく感じるのです。

だから「なぜ公式ドキュメントを読むのが苦しいのか…」と考えるとき、自分にこう言ってもいいと思います。

「私はすでにハンディキャップを抱えて頑張って走っている」

6. それでも…私たちにはいくつかのサバイバルスキルがあります

慰めだけで終わらせるのはもったいないので、私が書きながら身につけた ドキュメントサバイバル術 をいくつか付け加えます。

6-1. 「最初から最後まで読む」欲求を捨てる

公式ドキュメントは通常「参考書 + 辞書」のような感覚で作られています。
入門書のように「最初のページから最後まで読めば理解できる」構造ではありません。

だから私は：

「Getting Started / Quickstart / Tutorial」だけをざっくり見て
残りは
検索用
問題が起きたときに探す 用途と考えます。

6-2. 例で先に理解し、説明は後で読む

コードを一行書いてみる
エラーを一度起こしてみる
そのエラーメッセージを検索して再度ドキュメントを見る

すると文が突然こう変わります。

最初に読むとき：

「これが何を言っているのか分からない…」
何度失敗した後に再読すると：

「あ、これはあの時私が直面したエラーを指していたんだ…」

失敗経験があった後に読むと、ドキュメントは 物語のように読める瞬間 が訪れます。

6-3. 「自分の言語でメモする」

公式ドキュメントは仕方なく 彼らの言語 で書かれています。だから私はよくこうメモします。

「このオプションを true にすると、実質 XXX モード と考えて良い」
「この関数は『Xを作る工場』程度のイメージ」
「この部分は必ずこう暗記して使おう。深く理解は後で…」

後で自分が再び見る 「自分だけのドキュメント」 を作ると、公式ドキュメントとセットでより安心になります。（もちろん時々そのメモさえ「これ何？」になることもありますが…）

7. あなたが不足しているわけではない

この記事をここまで読んだなら、きっとあなたも公式ドキュメントの前でため息をついた経験があるでしょう。

何度も読んでも理解できない文
昨日見たはずなのに今日再び探すセクション
問題を解決してから初めて見える文

そのたびにぜひ覚えておいてほしい。

あなただけがそうではない
今も上手な開発者のほとんどが同じように迷っている
さらにそのライブラリを毎日使う人たちも公式ドキュメントより Stack Overflow や GitHub Issue を頻繁に検索 します。

公式ドキュメントは元々難しく書かれています。そしてそれはあなたのせいではありません。

私たちはただ、

理解できないときは再読
それでも分からないときはコードを書いてみる
失敗したら再びドキュメントを開く
そしてある日

「あ、だからこの人がこの文をこう書いたんだ…」と悟る過程を繰り返すだけです。

それが 開発者として生きること の一部ではないでしょうか。

だから今日もドキュメントの前で挫折している誰かにこう言いたい。

「あなたは間違っているわけではない。ただ、開発者の区間を通常速度で通過している だけだ」

私たちはまだドキュメントの前でぼんやりし、数十タブを開いて、昨日見たページを今日また探しながら開発しています。それでもプロジェクトは何とか動き、私たちはコードを一行ずつ学び続けます。🙂