じゃあ、おうちで学べる
本能を呼び覚ますこのコードに、君は抗えるか
文章力を分解してちゃんと文章を書く。
はじめに
文章を読むとは、自分の中で文章を再構築するということである。
あなたは技術記事を読んで「わかった」と思ったのに、いざ実装しようとすると何も書けなかった経験はないだろうか。ドキュメントを読んで「理解した」と思ったのに、同僚に説明しようとすると言葉が出てこなかった経験はないだろうか。
私にはある。何度もある。悲しい。
これは単なる理解不足ではない。もっと根本的な問題だ。私たちは「読む」と「書く」を別々のスキルだと思い込んでいる。しかし、それは違うと私は考えている。読むとき、私たちは頭の中で文章を再構築している。書き手の言葉を、自分のスキーマ（枠組み）に翻訳し、自分の言葉で理解し直している。読むことは、実は書くことなのだ。ただ、それが頭の中で行われているだけだ。だから、「わかった」と思っても実装できないのは、頭の中で再構築したものと現実の折り合いがついていないのだ。自分の言葉で書き直せていないのだ。
「読解力を分解してちゃんと文章を読む。」という記事を書いたあと、私はあることに気づいた。文章を読む力を分解して説明しようとすればするほど、自分が書く文章の問題点が見えてくるのだ。読み手がどこでつまずくかを想像すると、自分が読むときにどこでつまずいていたかが見えてくる。
そして、ある結論に辿り着いた。書けない人間は、読めない。これは挑発でも誇張でもない。書く力と読む力は、コインの表裏ではなく、同じものなのだ。
書く経験を通じて、私たちは「文章がどのように読まれるか」を学ぶ。一文が長すぎると読み手の認知負荷が上がること。主語が不明確だと読み手が推測を強いられること。構造が曖昧だと読み手が迷子になること。逆もまたあることだ。読む経験を通じて、私たちは「文章がどのように書かれるべきか」を学ぶ。明快な文章はどのような構造を持っているか。わかりやすい説明はどのように展開されるか。
読解力の記事では、読む力を3つの段階に分解した。今回の記事では、書く力を同じように分解していく。
第1段階：正確に書く
一文一義で書き、主語を明示し、構造を明確にする。悪文を書かないための技術的なスキルだ。
第2段階：誤読されないように書く
読み手のスキーマを想像し、知識の呪いを断ち切る。認知バイアスを考慮し、読み手が必要な情報にたどり着ける文脈を設計する。
第3段階：心を動かすように書く
書き出しで読者を引きつけ、常套句を避け、自分の言葉で語り、エピソードで心を動かす。ただし、これは技術記事やブログに適用される段階であり、技術ドキュメントには不要だ。
書くことで、初めて読めるようになる。読むことで、初めて書けるようになる。この循環的な関係を理解することが、文章力を高める第一歩だ。そして、この循環が複利的に機能する。書く力が向上すると読む力も向上し、読む力が向上するとまた書く力も向上する。この正のフィードバックループが、指数関数的な成長を生み出す。片方だけを鍛えようとしても、成長は頭打ちになる。両輪を回すことが、文章力を本質的に高める唯一の道だ。
では、なぜ書く力と読む力は、これほどまでに密接に結びついているのだろうか。その理由を、まず理解する必要がある。
このブログが良ければ読者になったり、nwiizoのXやGithubをフォローしてくれると嬉しいです。では、早速はじめていきます。
書く力と読む力は、なぜ表裏一体なのか
書けないということは、理解していないということだ
エラーログを読めない人は、エラーメッセージを吐き出させるときも曖昧な表現をする。「エラーが発生しました」とだけ書いて、どのエラーが、どの条件で、何が原因で発生したのかを書かない。なぜか？自分がエラーログを読むときに、これらの情報を抽出できていないからだ。というか想像できていないからだ。読んで困った時の自分を。読むときに「どこに何が書いてあるか」を理解できていない人は、吐き出させるときにも「どこに何を書くべきか」を理解できない。
これは単なる不注意ではない。書こうとして初めて、「何をどの順序で書くべきか」という問いに直面する。書こうとして初めて、「読み手は何を知りたいのか」という問いに直面する。この問いと格闘する過程で、私たちは文章の構造を深く理解する。技術記事を読んで「わかった」と思うのは、個々の文章を理解したということだ。しかし、それを実装できないのは、全体の構造を理解していないからだ。これは、ラバーダック・デバッギングと同じ原理だ。コードを声に出して説明しようとすると、理解の穴が見えてくる。文章を書こうとすると、読解の穴が見えてくる。書こうとして手が止まる瞬間、そこに理解の穴がある。
誤読された経験が、誤読を防ぐ力を育てる
理解の穴が見えるだけでは十分ではない。さらに重要なのは、自分が書いた文章がどう読まれるかを知ることだ。「この文章は誤解される」と事前に気づくには、自分が誤読された経験が必要だ。吐き出させた文章が意図と違う形で受け取られた経験。怒りのコメントを受けた経験。これらの痛い経験を通じて、人は「どんな書き方が誤解を生むか」を学ぶ。
誤読には、いくつかのパターンがある。
パターン1：主語の曖昧さによる誤読
この機能の実装が遅れています。仕様が複雑で理解に時間がかかっています。
書き手は「私」のつもりで書いている。しかし、読み手は「チーム全体」だと解釈するかもしれない。この誤読は、書き手が主語を省略したことで生じる。
パターン2：文脈の欠如による誤読
この実装方法は悪くない。
書き手は、他の実装方法と比較して「悪くない」と言っている。しかし、読み手は、この実装方法が「及第点」程度だと解釈するかもしれない。
パターン3：二重否定による誤読
この問題は無視できない。
書き手は「重要だ」と言いたい。しかし、読み手は「ある程度重要だが、最優先ではない」と解釈するかもしれない。
誤読された経験は、痛い。しかし、その痛みこそが、書く力と読む力を同時に高める。書く経験が乏しい人は、読むときにも「書き手の意図」を想像できない。
スキーマは読み書き両方で機能する
誤読を防ぐには、さらに深い理解が必要だ。それは、読み手と書き手でスキーマが異なるという理解だ。人はスキーマを通して文章を理解する。スキーマとは、私たちが頭の中に持っている知識の枠組みのこと。例えば、「非同期処理」というキーワードを見たとき、Rustエンジニアの頭の中では、tokio、async/await、Future traitといった関連する概念が自動的に呼び出される。
しかし、スキーマは読むときだけでなく、書くときにも機能している。そして、書くときのスキーマの働き方が、しばしば問題を引き起こす。あなたが「非同期処理を実装した」と書くとき、あなたの頭の中には「非同期処理」についての豊富なスキーマがある。だから、読み手もそのスキーマを共有していると無意識に仮定してしまう。これを「知識の呪い」と呼ぶ。
【悪い例】非同期処理を実装しました。これでパフォーマンスが改善されます。
書き手にとって、これは十分に明確だ。しかし、読み手はどうか？Rustエンジニアは「tokioのasync/awaitを使うのか」と想像する。Goエンジニアは「goroutineを使うのか」と想像する。非同期処理に馴染みのないエンジニアは「何が改善されるのか」すらわからない。
書く力が高い人は、「読み手は自分とは違うスキーマを持っている」と意識的に認識する。そして、読み手のスキーマを想像し、橋を架けるように書く。
【良い例】非同期処理を実装しました。従来は3つのマイクロサービスへのHTTPリクエストを順番に実行していたため、合計で3秒かかっていました。今回、Rustのtokioとasync/awaitを使ってこれらのリクエストを並行実行するように変更しました。その結果、3つのリクエストが同時に実行されるため、最も遅いリクエスト（1秒）の時間だけで完了するようになりました。これにより、全体の処理時間が3秒から1秒に短縮され、APIのレスポンスタイムが大幅に改善されました。
では、この「読み手のスキーマを想像する力」は、どうやって獲得できるのか？答えは、読み手として多様な文章に触れ、「わからない」を経験することだ。自分が知らない分野の技術記事を読んで、「専門用語が多くてわからない」と感じる。その経験が、書き手として「専門用語を使うときは説明を加えよう」という意識を育てる。
書くことは、読む力を鍛える最良の訓練
ここまで見てきたように、書く経験は読む力を高める。しかし、その逆も真だ。読む経験は書く力を高める。この循環を最も効果的に回す方法が、実は書くことなのだ。なぜか？書こうとすると、言語化できない部分に直面するからだ。頭の中では理解しているつもりでも、いざ文章にしようとすると言葉が出てこない。この瞬間、あなたは「本当は理解していなかった」と気づく。
しかし、問題はもっと深い。ちゃんと読むとは、自分の中でちゃんと書くということでもある。複雑な文章を読むとき、私たちは無意識のうちに「これはつまり、こういうことだな」と自分の言葉で要約している。この「内なる執筆」ができない人は、文章を読んでも理解が浅い。
例を見てみよう。技術記事に「エラーハンドリングを実装すると、システムの信頼性が向上する」と書いてある。
浅い読み方：「エラーハンドリングを実装すると信頼性が向上するのか。なるほど。」
深い読み方：「エラーハンドリングを実装すると信頼性が向上する、と言っている。なぜか？エラーハンドリングがないと、エラーが発生したときにプログラムがパニックして停止してしまう。その結果、ユーザーはサービスを使えなくなる。一方、エラーハンドリングを実装すれば、エラーが発生してもプログラムは継続でき、ユーザーに明確なエラーメッセージを返せる。つまり、『信頼性が向上する』とは『エラー時でもサービスを継続できる』という意味だな。」
深い読み方をしている人は、頭の中で文章を書いている。この「内なる執筆」の能力は、実際に書く経験を通じて鍛えられる。外に向けて文章を書くとき、私たちは「どう表現すれば伝わるか」を考える。この試行錯誤が、内なる執筆の能力を高める。だから、外に向けて書く訓練をすることは、内に向けて書く力も鍛える。
このように、書く力と読む力は表裏一体だ。では、具体的にどう書けばよいのか。読解力の記事と同様、書く力も3つの段階に分解して見ていこう。
第1段階：正確に書く
読解力の第1段階は「書かれていることを正確に理解する力」だった。文章力の第1段階は、「伝えたいことを正確に伝える力」だ。これは、技術的なスキルだ。感性や才能ではなく、学習可能なスキルだ。
悪文とは何か。それは、一義的に解釈できない文章だ。一つの文を読んで、複数の意味に解釈できてしまう。主語が不明確で、誰が何をしているのかわからない。修飾関係が複雑で、何がどこにかかっているのか判然としない。こうした構造的な問題が、悪文を生む。文章を書くコツは、芸術的な名文を書くことではない。読みにくい「悪文」を書かないことである。
では、悪文を防ぐにはどうすればよいか。ここでは四つ紹介します。他にも悪文を分かりやすくする方法はいくらかありますがたくさん本が出ていますのでそちらを参考にしてほしいです。
一文一義で書く
【悪い例】デプロイ作業中にDBマイグレーションが失敗したため、問題箇所をスキップすればデプロイは可能ですが、Xモジュールへの影響が不明なので、明日Yさんが出社してから対応するか、今日スキップしてデプロイするか、どちらが良いと思いますか？
この一文には、6つの義が詰め込まれている。読み手は、これらすべてを一度に処理しなければならない。認知負荷が高すぎる。なぜ一文一義が重要なのか？人間の作業記憶（ワーキングメモリ）の容量は限られている。一文が長く、複数の義が含まれていると、読み手は文の途中で最初の部分を忘れてしまう。一文一義で書くことは、読み手の認知リソースを尊重することだ。
【良い例】デプロイ作業中、DBマイグレーションに失敗しました。問題箇所をスキップすればデプロイは可能ですが、Xモジュールへの影響が不明です。対応方針を相談させてください。以下の2つの選択肢のうち、どちらが良いでしょうか？A. 明日Yさんが出社後、一緒に影響範囲を調査してから対応するB. 今日、問題箇所をスキップしてデプロイする
一文一義の原則を守るには、3つのルールがある。
ルール1：文章は短くする
長文は悪文。一文は40字以内を目指す。どうしても長くなる場合は、60字以内に抑える。
ルール2：形容詞と被形容詞はなるべく近づける
修飾関係を明確にする。離れていると、読み手は修飾関係を推測しなければならない。
ルール3：一つの文に、主語と述語はひとつずつ
複雑な構造を避ける。複数の主語・述語があると、文の構造が複雑になり、理解が難しくなる。
短く、近く、シンプルに。これが機能的な文章の基本だ。
主語を明示する
一文一義を守るだけでは不十分だ。次に重要なのは、誰が何をしているかを明確にすることだ。日本語は主語を省略できる言語だ。しかし、文章を書くとき、特に技術文書やビジネス文書を書くとき、文脈が常に明らかとは限らない。主語を省略すると、3つの問題が生じる。
問題1：責任の所在が不明確になる
【悪い例】バグを修正しました。【良い例】私がバグを修正しました。
問題2：行為者が不明確になる
【悪い例】テストを実行して、結果を確認しました。【良い例】私がテストを実行しました。Aさんが結果を確認しました。
問題3：複数の解釈が可能になる
【悪い例】レビュー後、デプロイしました。【良い例】Aさんのレビュー後、私がデプロイしました。
では、どうすればよいか？主語を省略してもよい場合と、省略してはいけない場合を区別する。主語を省略してもよい場合：直前の文と同じ主語の場合、文脈から主語が明らかな場合。主語を省略してはいけない場合：主語が変わる場合、責任の所在を明確にする必要がある場合、複数の解釈が可能な場合。
冗長さを避ける
正確に書くことは重要だが、冗長に書くことは避けなければならない。必要な情報だけを、必要な長さで書く。冗長な文章は、読み手の時間を無駄にする。忙しいエンジニアは、冗長な文章を読む時間がない。冗長な文章は、重要な情報を埋もれさせる。冗長さには、いくつかのパターンがある。
パターン1：同じことを繰り返す
【悪い例】この問題は重要な問題です。なぜなら、この問題を放置すると、ユーザーに影響が出る重大な問題だからです。【良い例】この問題は重要です。放置するとユーザーに影響が出ます。
パターン2：不要な修飾語を使う
【悪い例】非常に重要な機能の実装を丁寧に進めています。【良い例】重要な機能を実装中です。
「非常に」「丁寧に」といった修飾語は、情報を追加していない。削除しても意味は変わらない。
パターン3：回りくどい表現を使う
【悪い例】バグを修正することに成功しました。【良い例】バグを修正しました。
「〜することに成功しました」は、「〜しました」で十分だ。
冗長さを避けるには、3つの原則がある。
原則1：削除できる言葉は削除する
文を書いたら、一語ずつ削除してみる。削除しても意味が変わらない言葉は、不要だ。
原則2：同じ情報は一度だけ書く
繰り返しは、強調のために意図的に使う場合を除いて避ける。
原則3：具体的な動詞を使う
「実施する」「行う」「実行する」などの抽象的な動詞ではなく、「修正する」「追加する」「削除する」などの具体的な動詞を使う。
簡潔さは、尊重の表現だ。読み手の時間を尊重し、認知リソースを尊重する。
構造を明確にする
一文一義で書き、主語を明示し、冗長さを避ける。しかし、それだけでは不十分だ。文章全体の構造を明確にする必要がある。箇条書きと文章の使い分けは、書き手の重要なスキルだ。並列関係の情報は箇条書きで、因果関係の情報は文章で。なぜ構造が重要なのか？構造は、思考の可視化だからだ。
構造を明確にする最も基本的な単位は、パラグラフ（段落）だ。一つのパラグラフには、一つの主張しか含めない。構造を明確にするには、3つのレベルがある。
レベル1：文のレベル
一文一義。主語・述語を明確に。
レベル2：パラグラフのレベル
一つのパラグラフに一つの主張。パラグラフの最初の文（トピックセンテンス）で、パラグラフの内容を要約する。
レベル3：セクションのレベル
関連するパラグラフをセクションにまとめる。セクションに見出しをつける。見出しの階層を明確にする。
この3つのレベルの構造が明確な文章は、読み手にとって理解しやすい。第1段階の「正確に書く」力を身につけると、少なくとも誤解されない文章が書けるようになる。しかし、それだけでは不十分だ。読み手は、あなたの意図を汲み取ろうとしてくれるとは限らない。次の段階では、より能動的に誤読を防ぐ技術を学ぶ。
第1段階の実践訓練
訓練1：一文一義の練習
自分が書いた文章を見直して、一文に複数の義が含まれていないか確認する。含まれていたら、文を分割する。最初は40字を超える文をすべて分割してみよう。
訓練2：主語の明示
自分が書いたメッセージやコメントで、主語が省略されている箇所を見つける。「誰が」を明示すると、どう変わるか確認する。
訓練3：冗長さの削除
自分が書いた文章から、削除できる言葉を見つける。「非常に」「丁寧に」「〜することに成功しました」などの表現を見つけて削除してみる。意味が変わらないことを確認する。
訓練4：構造の可視化
長い文章を書くときは、最初に見出しの構造だけを書く。各セクションに何を書くか、パラグラフごとに何を伝えるかを決めてから書き始める。
訓練5：要約を書く
技術記事を読んだら、3行で要約してみる。要約できないなら、理解できていない証拠だ。記事を見ずに、覚えていることを書き出し、重要な情報だけを3行にまとめる。
AIを使った第1段階の訓練
生成AIは、第1段階の訓練に有効だ。
AIに構造をチェックさせる
自分が書いた文章をAIに渡して、「一文一義になっているか」「主語が明確か」「冗長な表現はないか」「構造が明確か」をチェックさせる。しかし、AIの指摘を盲目的に受け入れるのではなく、自分で判断する。
AIの文章を添削する
AIに技術ドキュメントを書かせて、それを添削する。「この文は長すぎる」「ここは主語が不明確」「構造が混乱している」「この表現は冗長だ」。AIの文章の問題点を指摘する訓練は、自分の文章の問題点に気づく訓練になる。
重要な注意点
AIに書かせることに慣れすぎると、「どう表現すれば伝わるか」を考える機会を失う。AIは初稿の生成やチェックリストとして使い、最終的な判断は必ず自分で行う。
第2段階：誤読されないように書く
読解力の第2段階は「書かれていない意図を汲み取る力」だった。文章力の第2段階は、「読み手の誤読を防ぐ力」だ。第1段階では、文章の構造的な問題を防ぐ方法を学んだ。一文一義で書き、主語を明示し、冗長さを避け、構造を明確にする。しかし、構造が正しくても、誤読は起きる。なぜか？読み手と書き手でスキーマが異なるからだ。
前のセクションで「知識の呪い」について説明した。ここでは、その呪いを断ち切り、読み手のスキーマに合わせて書く具体的な方法を学ぶ。
技術ドキュメントの品質は、ここで決まる
特に技術ドキュメントにおいては、第2段階が品質を決定づける。第1段階の「正確に書く」は、技術ドキュメントの必要条件だ。構造が曖昧で、主語が不明確で、冗長な技術ドキュメントは、そもそも読むに値しない。しかし、第1段階をクリアしただけでは、良い技術ドキュメントにはならない。
技術ドキュメントの良し悪しを分けるのは、読み手が迷わず、誤解せず、必要な情報にたどり着けるかだ。これこそが第2段階の本質だ。構造的には正しいが、読み手のスキーマを無視したドキュメント。専門用語が説明なしに使われ、前提知識が明示されず、文脈が欠如しているドキュメント。こうしたドキュメントは、正確ではあるが、使えない。
逆に、読み手のスキーマを想像し、知識の呪いを断ち切り、読み手が必要な情報にたどり着ける文脈を設計したドキュメントは、読み手を迷わせない。読み手は、探している情報をすぐに見つけられる。誤解なく理解できる。そして、次のアクションを取れる。
APIリファレンス、設計書、運用手順書、トラブルシューティングガイド。これらの技術ドキュメントは、第3段階の「心を動かす」手法は不要だ。感情に訴える必要はない。しかし、第2段階の「誤読されないように書く」技術は、絶対に必要だ。技術ドキュメントを書くとき、常に自問すべきだ。「読み手は、この情報を探しているとき、どんな状況にいるのか？」「読み手は、どのくらいの前提知識を持っているのか？」「読み手は、この用語を知っているのか？」これらの問いに答えることが、使える技術ドキュメントと使えない技術ドキュメントを分ける。
読み手のスキーマを想像する
ドキュメントを書くとき、まず問うべきは「読み手は誰か？」だ。読み手は誰か？何を知っていて、何を知らないか？どんな問題を解決しようとしているか？知識の呪いを断ち切るには、3つの方法がある。
方法1：具体化する
抽象的な言葉を、具体的な言葉に置き換える。
方法2：例示する
抽象的な概念を、具体的な例で説明する。
方法3：段階的に説明する
最も基本的な概念から始めて、徐々に詳細に入る。
読み手のスキーマを想像する能力は、読み手として多様な文章に触れ、「わからない」を経験することで獲得できる。しかし、スキーマを想像するだけでは不十分だ。次に重要なのは、読み手の認知バイアスを考慮することだ。
認知バイアスを考慮する
読み手がどんなバイアスを持っているかを想定し、誤読を防ぐ。
パターン1：二重否定による混乱
【誤読されやすい例】この実装方法は悪くない。【誤読されにくい例】この実装方法は、実用上十分な性能を持っています。具体的には、毎秒1000リクエストを処理できます。
パターン2：曖昧な数量表現
【誤読されやすい例】この問題は重要です。【誤読されにくい例】この問題は、今週中に対応が必要です。なぜなら、放置するとユーザーがログインできなくなるからです。
パターン3：主観的な評価
【誤読されやすい例】このツールは使いやすい。【誤読されにくい例】このツールは、5分で環境構築できます。コマンド一つで起動でき、GUIで操作できます。
認知バイアスを考慮した文章は、客観的で、具体的で、測定可能だ。
文脈を設計する
技術記事を書くとき、どこまで前提知識を説明すべきか。この判断には原則がある。
原則1：読み手のレベルに合わせる
初心者向けの記事なら、基本的な概念から説明する。上級者向けの記事なら、基本は省略して応用に焦点を当てる。
原則2：この記事で必要な知識だけを説明する
この記事を理解するために最低限必要な知識だけを説明する。
原則3：外部リソースを活用する
詳細な説明が必要な場合は、外部の良質な記事へのリンクを示す。
テンプレートを活用する
第2段階における最も実用的な方法の一つが、テンプレートの活用だ。テンプレートは、第1段階の「構造を明確にする」技術と似ているが、その目的は異なる。第1段階では、書き手が構造的に正しい文章を書くためのツールだった。第2段階では、読み手が迷わず、必要な情報にたどり着けるためのツールだ。
テンプレートには、3つの利点がある。
利点1：読み手の予測可能性を高める
同じ構造の文章を繰り返し読むと、読み手は次に何が来るかを予測できる。予測可能性は、理解を助ける。
利点2：必要な情報を漏れなく提供する
読み手が探している情報を必ず含められる。チェックリストとして機能する。
利点3：読み手の認知負荷を減らす
毎回異なる構造だと、読み手は「どこに何が書いてあるか」を探すコストがかかる。テンプレートは、この探索コストを削減する。
例えば、バグ報告のテンプレートは次のようになる。
## 概要[バグの概要を一行で]## 再現手順1. [手順1]2. [手順2]3. [手順3]## 期待される動作[何が起きるべきか]## 実際の動作[実際に何が起きたか]## 環境- OS: - ブラウザ: - バージョン: ## 追加情報[スクリーンショット、ログなど]
このテンプレートを使えば、読み手（バグを修正するエンジニア）は、必要な情報をすぐに見つけられる。「再現手順はどこだ？」「どの環境で起きたんだ？」と探す時間を削減できる。
技術ドキュメントのテンプレートは次のようになる。
## 概要[この文書が何について説明するか]## 前提条件[読者が知っているべきこと、必要な環境]## 手順[具体的な手順、コード例]## トラブルシューティング[よくある問題と解決法]## 参考資料[関連するドキュメント、リンク]
プルリクエストのテンプレートは次のようになる。
## 変更内容[何を変更したか]## 変更理由[なぜ変更したか]## 影響範囲[どの機能に影響するか]## テスト[どのようにテストしたか]## レビューのポイント[レビュアーに特に見てほしい箇所]
テンプレートを使う際の注意点：テンプレートは、読み手を助ける道具だ。しかし、テンプレートに縛られすぎてはいけない。状況に応じて、テンプレートをカスタマイズする。不要なセクションは削除し、必要なセクションは追加する。重要なのは、「読み手が必要な情報にたどり着けるか」という問いだ。テンプレートは、この問いに答えるための手段であって、目的ではない。
第2段階の「誤読されないように書く」力を身につけると、読み手に正確に情報を伝えられるようになる。読み手のスキーマを想像し、認知バイアスを考慮し、読み手が必要な情報にたどり着ける文脈を設計する。しかし、それだけでは不十分だ。情報を伝えるだけでなく、読み手の心を動かす必要がある。なぜなら、心が動かなければ、読み手は行動しないからだ。次の段階では、その方法を学ぶ。
第2段階の実践訓練
訓練1：説明を書く
誰かに技術を説明する文章を書く。相手のスキーマを想像しながら書く訓練だ。「この人は何を知っていて、何を知らないか？」を考える。具体的には、次のような取り組みができる。初心者向けに、自分が得意な技術を説明する記事を書く。専門用語を使うたびに、「この用語は説明が必要か？」と自問する。書いた後、その分野に詳しくない人に読んでもらい、わからなかった箇所を聞く。
訓練2：批判的に読む
技術記事に対する建設的な批判を書く。記事の文脈を理解した上で、「この前提が変わったら？」「別のアプローチは？」と考える。批判には3つのレベルがある。レベル1：感情的な反応（「間違っている」だけ）。レベル2：代替案の提示（文脈を無視）。レベル3：文脈を踏まえた建設的な疑問。レベル3を目指す。記事の前提条件を理解し、その上で具体的な質問を提示する。
訓練3：テンプレートの作成
自分がよく書く文書（バグ報告、技術ドキュメント、プルリクエストなど）のテンプレートを作る。ただし、第1段階の「構造を明確にする」だけでなく、「読み手が必要な情報にたどり着けるか」という視点で作る。読み手が最も知りたい情報は何か？それをどこに配置すれば見つけやすいか？
AIを使った第2段階の訓練
AIに読み手のスキーマを想像させる
自分が書いた技術文章をAIに渡して、「初心者が読んだらどこでつまずくか」を予測させる。AIの予測を参考にしながら、自分で判断する。
AIと対話しながら書く
AIに質問しながら記事を書いていく。「この説明は初心者にもわかりますか？」「もっと具体的にするには？」。しかし、最終的な判断は自分で行う。
重要な注意点
AIに書かせることに慣れると、「内なる執筆」の能力が衰える。文章を読むとき、私たちは頭の中で文章を再構築している。しかし、AIに書かせることに慣れると、この「内なる執筆」をしなくなる。AIは対話の相手として使い、思考そのものをAIに任せてはいけない。
第3段階：心を動かすように書く
読解力の第3段階は「本当に重要なことを見抜く力」だった。文章力の第3段階は、「読み手の心を動かす力」だ。なお、この第3段階は、技術記事、ブログ、プレゼンテーションなど、読者の心を動かす必要がある文章に適用される。技術ドキュメント（APIリファレンス、設計書、仕様書など）では、第1段階と第2段階で十分だ。むしろ、客観性と正確性が重視される技術ドキュメントには、この段階の手法は合わない場合が多い。
「読みたいこと」とは何か？多くの人が誤解する。「読みたいこと」とは、「自由に好き勝手に自分の気持ちを書くこと」ではない。「読みたいこと」とは、自分が読者だったら読みたいと思うものだ。自分が本屋で金を出して買いたいと思うもの。自分が時間を使って読みたいと思うもの。書きたいことではない。読みたいことだ。これは、他人の視点に立てという話ではない。徹底的に自分の視点で、自分が読者として読みたいかどうかを問うということだ。この問いは、書きたいことを書く自由よりも、はるかに厳しい制約だ。
第1段階では構造を学び、第2段階では誤読を防ぐ技術を学んだ。しかし、それだけでは読み手の心は動かない。心を動かすには、まず読者を引きつける必要がある。
最初の三行で撃つ
最初の一文、長くても三行くらいで心を撃たないと、忙しい読者は逃げていく。読者はあなたに興味がない。読者にとって、あなたの書こうとするテーマはどうでもいい。冷厳な現実だ。では、どうすれば最初の三行で読者を撃てるのか？
方法1：問題を提示する
読者の痛みに触れる。「ああ、ある」と思った読者は、続きを読む。
方法2：驚きを与える
常識に反する。「え、どういうこと？」と思った読者は、続きを読む。
方法3：具体的な利益を示す
読者に利益を約束する。「それは知りたい」と思った読者は、続きを読む。
しかし、最も重要なのは、お前が何者かは、読者にとって関係ないということだ。
【悪い例】私は10年間、技術記事を書いてきました。その経験から学んだ文章術を共有します。
読者は、基本的にあなたの経歴に興味がない。あなたが何年エンジニアをやってきたか、どんな実績があるか、ほとんどの読者にとってどうでもいい。読者が知りたいのは、「この記事は自分の問題を解決してくれるのか？」「面白い時間が過ごせるか？」「読む価値のある新しい視点があるのか？」「具体的で実践できる内容なのか？」「読んだ後、自分は何ができるようになるのか？」。これらの問いだけだ。書き手の自己紹介から始まる記事は、これらの問いに答えていない。だから、読者は離れていく。
【良い例】エラーメッセージを読めない人は、エラーメッセージを吐き出させるときも曖昧だ。なぜか？
この書き出しは、問題提起だ。読者は「なぜだろう？」と思う。書き出しで読者を引きつけることができた。しかし、心を動かすにはそれだけでは不十分だ。次に必要なのは、空虚な言葉を避けることだ。
常套句を避ける
書き出しで読者を引きつけても、内容が空虚なら読者は離れていく。そして、内容を空虚にする最大の敵が、常套句だ。常套句は、まさに「わかったつもり」を生み出す装置だ。
このアプローチはベストプラクティスです。
「ベストプラクティス」とは何か？誰が決めたのか？どういう文脈で最適なのか？なぜ最適なのか？これらの問いに答えない限り、「ベストプラクティス」という言葉は空虚だ。常套句には、いくつかのパターンがある。
パターン1：抽象的なバズワード
ベストプラクティス、レバレッジ、シナジー、エンパワーメント、イノベーション。これらの言葉は、具体的な内容を隠蔽する。
パターン2：「としたもんだ表現」
〜というもの、〜としたもの、〜してしまった。これらの表現は、思考停止の証だ。
パターン3：擬音語・擬態語・流行語
エモい、ほっこり、ざっくり、さくっと。これらの言葉は、具体性を欠く。
常套句を避けることは、思考を深めることだ。「ベストプラクティス」と書こうとして、「本当にベストなのか？」と自問する。この思考の過程が、文章を具体的にし、説得力を高める。常套句を避け、具体的に書くことができたら、次は自分にしか書けない内容を書く。
自分の言葉で書く
【常套句に逃げる例】Rustの所有権システムは学習が難しい。でも、理解すれば強力だ。
これは誰でも書ける文章だ。
【自分の言葉で書く例】私がRustの所有権システムを理解するのに、3ヶ月かかった。最初の1ヶ月は、borrowチェッカーのエラーが理解できず、「なぜこのコードが動かないのか」と毎日フラストレーションを感じていた。「cannot borrow `*x` as mutable because it is also borrowed as immutable」このエラーメッセージを見るたびに、「Cのポインタのように自由に使わせてくれよ」と思っていた。転機は、所有権を「責任の所在」として捉え直してからだ。「このデータに対する責任は誰が持つのか」と考えるようになってから、borrowチェッカーのメッセージが「監査人の指摘」として理解できるようになった。
この文章は、あなたにしか書けない。あなたの体験、あなたの発見だ。自分の言葉で書くには、3つの要素が必要だ。
要素1：具体的な体験
抽象的な表現ではなく、具体的な体験を書く。
要素2：五感で世界を切り取る
見て、聞いて、触れて、嗅いで、味わって。そして、正確に書く。
要素3：思考の過程
思考の過程を書くことで、読み手はあなたの思考をたどることができる。
自分の言葉で書くとは、言い換えることだ。「所有権」という抽象的な概念を、「責任の所在」という具体的な比喩で言い換える。言い換えるとは、考えることだ。しかし、自分の言葉で書くだけでは不十分だ。言葉だけでは、読み手の心は十分には動かない。次に必要なのは、エピソードの力だ。技術ブログの書き方はここに書いているので読んでみてほしいです。
響く文章は説明しない
【説明する例】ドキュメントを書くことは重要です。なぜなら、ドキュメントがないとユーザーが困るからです。
説明は響かない。
【エピソードで語る例】私が初めてオンコール当番を担当したとき、深夜2時にアラートが鳴った。Datadogのダッシュボードには、「CPU usage > 80%」というアラートしか表示されていなかった。「どのサービスのCPUが高いのか」「何が原因なのか」「どうやって対処すればいいのか」何もわからず、私は1時間を無駄にした。結局、先輩を叩き起こして対処してもらった。先輩は5分で原因を特定し、10分で対処した。翌朝、先輩に聞いた。「なぜそんなに早く対処できたんですか？」先輩は言った。「アラートに必要な情報が書いてあったからだよ」そのとき誓った。自分がアラートを作るときは、必ずRunbookへのリンクを含めようと。それから3年、私はこの誓いを守っている。
エピソードは響く。具体的な場面、具体的な感情、具体的な決断。これらが、読み手の心を動かす。
なぜエピソードは説明よりも響くのか
エピソードが響く理由は、共感にある。読み手は、あなたの物語の中に自分を見出す。「深夜2時のアラート」「何もわからない焦り」「先輩を叩き起こす申し訳なさ」。これらの感情は、多くのエンジニアが経験したことがある。あるいは、いつか経験するかもしれない。だから、読み手は「ああ、わかる」と思う。この「わかる」という感覚が、共感だ。
共感は、説明では生まれない。「ドキュメントは重要です」という説明は、頭では理解できる。しかし、心は動かない。一方、エピソードは、読み手を物語の中に引き込む。読み手は、あなたの経験を追体験する。あなたの焦りを感じ、あなたの学びを共有する。
共感してもらえる物語には、3つの条件がある。
条件1：普遍的な感情を含む
誰もが経験したことがある感情。焦り、不安、喜び、後悔、発見。技術記事であっても、これらの感情は普遍的だ。「わからない」という不安は、すべてのエンジニアが経験している。「理解できた」という喜びも、すべてのエンジニアが知っている。
条件2：具体的な状況を描く
抽象的な「困った経験」ではなく、「深夜2時のアラート」という具体的な状況。読み手は、具体的な状況を通して、あなたの経験を追体験できる。「1時間を無駄にした」という具体的な時間。「先輩を叩き起こした」という具体的な行動。
条件3：弱さを見せる
完璧な成功物語では、共感は生まれない。「わからなかった」「失敗した」「恥ずかしかった」。こうした弱さを見せることで、読み手は「この人も自分と同じように悩んでいるんだ」と感じる。技術記事では、技術的な卓越性を示すことよりも、学びのプロセスを見せることの方が、しばしば価値がある。
共感は、信頼を生む。読み手があなたの物語に共感すると、あなたの言葉を信頼するようになる。「この人は、自分と同じ問題に直面して、それを乗り越えた人だ」。この信頼が、読み手を行動に移させる。説明では信頼は生まれない。しかし、共感できる物語は、信頼を築く。
ただし、共感を意図的に操作しようとしてはいけない。作られた感情や、誇張された困難は、読み手に見抜かれる。本当に経験したこと、本当に感じたこと、本当に学んだことを書く。その誠実さが、最も強い共感を生む。
エピソードで語るには、ストーリーの構造が必要だ。
- 状況 - どんな状況だったか
- 問題 - 何が問題だったか
- 行動 - 何をしたか
- 結果 - どうなったか
- 学び - 何を学んだか
自分の言葉で書き、共感してもらえるエピソードで語る。しかし、それでも心を動かすには、もう一つ必要なものがある。それは、あなたの生き方や物語そのものだ。
書くことは生きること
「書くことは生きること」。文章を書くことは、技術ではない。生き方だ。思索が深まるほどに、世界の切り取り方が変わり、自分が変わる。
技術記事を書くとき、私たちは技術を説明しているだけではない。私たちは、技術を通して世界を理解している。「なぜこの技術は存在するのか」「どんな問題を解決するのか」「どんな未来を可能にするのか」。これらの問いに答えることは、技術を理解することであり、同時に世界を理解することだ。そして、これらの問いに答える過程で、私たちは自分自身を理解する。書くことで、私たちは自分になる。
書くことは、自分の物語を紡ぐこと
書くことは、単に情報を伝えることではない。自分の物語を紡ぐことだ。
あなたがエンジニアとして生きてきた日々。深夜のデバッグ、突然の本番障害、チームでの議論、新しい技術との出会い、失敗から学んだ教訓。これらすべてが、あなたの物語だ。書くとは、これらの断片的な経験を、一つの物語として編集することだ。
物語には、3つの力がある。
力1：意味を与える力
バラバラの経験は、物語として語られることで意味を持つ。「深夜2時のアラート」という出来事は、それ単体では単なる不運だ。しかし、「そのとき誓った。自分がアラートを作るときは、必ずRunbookへのリンクを含めようと」という学びと結びつくとき、その出来事は意味を持つ。物語は、経験に意味を与える。
力2：つながりを生む力
あなたの物語は、あなただけのものではない。読み手は、あなたの物語の中に自分を見出す。「ああ、自分もそうだった」「いつか自分もそうなるかもしれない」。物語は、書き手と読み手をつなぐ。そして、読み手同士もつなぐ。「この経験は自分だけじゃなかったんだ」という安心感。物語は、孤独を癒す。
力3：未来を変える力
物語は、過去を語るだけではない。未来を変える。あなたが「誓った」物語は、あなたの行動を変える。そして、その物語を読んだ人の行動も変える。「自分もRunbookを書こう」「自分も後輩のために道を残そう」。物語は、行動を促す。
しかし、物語を紡ぐには、勇気が必要だ。
自分の失敗を書くこと。「わからなかった」「1時間を無駄にした」「先輩を叩き起こした」。これらの弱さを見せることは、恥ずかしい。しかし、完璧な成功物語は、誰の心も動かさない。読み手が求めているのは、完璧なヒーローではない。同じように悩み、同じように失敗し、それでも前に進んだ人の物語だ。
あなたの物語は、すでにある。日々の仕事の中で、あなたは物語を生きている。書くことは、その物語を可視化することだ。そして、可視化することで、物語はより明確になる。「自分は何を大切にしているのか」「どんな価値観で生きているのか」「どこに向かっているのか」。物語を書くことで、あなたは自分の物語を理解する。
わたしにしか、書けないものは、ある。わたしにしか、紡げない物語は、ある。そう信じることから、文章は始まる。
第3段階の実践訓練
なお、これらの訓練は、技術記事、ブログ、プレゼンテーションを書く人向けだ。技術ドキュメントを書く人は、第1段階と第2段階の訓練に集中してほしい。
訓練1：書き出しを3パターン書く
記事を書くとき、最初に書き出しを3パターン考える。問題提示型、驚き型、利益提示型。それぞれ書いてみて、最も効果的なものを選ぶ。
訓練2：常套句を見つけて書き直す
自分が書いた文章から、常套句を見つけて具体的に書き直す。「ベストプラクティス」→「なぜベストなのか？どういう条件で？」と問う。技術記事では、抽象的な言葉が説得力を失わせる。
訓練3：自分の体験を書く
技術的な概念を説明するとき、自分の体験を具体的に書く。五感を使って世界を切り取る。「3ヶ月かかった」「毎日フラストレーションを感じた」「エラーメッセージを見るたびに」。
訓練4：説明ではなく、エピソードで語る
「ドキュメントは重要だ」と説明するのではなく、ドキュメントがなくて困った具体的なエピソードを語る。状況、問題、行動、結果、学びの5つを含める。
訓練5：自分の文章を読み直す
書いた直後ではなく、時間をおいて読み直す。3つの視点で読んでみよう。初心者として（前提知識がない人として）、批判者として（批判的な読者として）、誤読する人として（わざと誤読してみる）。
AIを使った第3段階の訓練
AIに書き出しを生成させて、添削する
AIに記事の書き出しを生成させる。そして、「この書き出しは読者を引きつけるか？」「自慢になっていないか？」「問題提起ができているか？」と批判的に評価する。
AIに常套句を指摘させる
「この文章で常套句や抽象的な表現を指摘してください」とAIに依頼する。しかし、AIが指摘した表現がすべて悪いわけではない。文脈によっては効果的な場合もある。自分で判断する。
AIに自分の文章を批判させる
自分が書いた技術記事をAIに読ませて、「この文章で心が動く部分はどこですか？」「もっと感情的に響く部分はありますか？」と聞く。しかし、AIの提案を盲目的に受け入れるのではなく、自分の声を保つことを意識する。
AIには書けないものを書く
あなたの体験、あなたの発見、あなたの視点。これらは、AIには書けない。AIを使うとき、この原則を忘れないこと。「わたしにしか、書けないものは、ある」。
おわりに
「読解力を分解してちゃんと文章を読む。」を書いたとき、私は気づいた。読む力を説明しようとすることは、書く力を鍛えることでもあると。そして今、「文章力を分解してちゃんと文章を書く。」を書き終えて、改めて実感する。書く力を説明しようとすることは、読む力を鍛えることでもあると。
読む力と書く力は、別々のスキルではない。同じスキルの異なる側面だ。この記事の冒頭で、私はこう書いた。「技術記事を読んで『わかった』と思ったのに、いざ実装しようとすると何も書けなかった経験はないだろうか」。なぜ実装できないのか。答えは明確だ。頭の中で再構築できていないからだ。読むとは、実は書くことなのだ。ただ、それが頭の中で行われているだけだ。だから、読む力を高めたいなら、書くことだ。書く力を高めたいなら、読むことだ。この循環が、複利的に機能する。
第1段階では、正確に書く技術を学んだ。一文一義、主語の明示、構造の明確化。これは、悪文を書かないための必要条件だ。第2段階では、誤読を防ぐ技術を学んだ。読み手のスキーマを想像し、知識の呪いを断ち切り、文脈を設計する。特に技術ドキュメントでは、この段階が品質を決定づける。第3段階では、心を動かす技術を学んだ。書き出しで引きつけ、常套句を避け、自分の言葉で語り、エピソードで伝える。ただし、これは技術記事やブログに適用される段階であり、技術ドキュメントには不要だ。
しかし、文章を書くことの意味は、スキルを高めることだけではない。書くことは、思考を深めることだ。思索が深まるほどに、世界の切り取り方が変わり、自分が変わる。書くことは、世界を理解することだ。技術を説明しようとするとき、私たちは「なぜこの技術は存在するのか」「どんな問題を解決するのか」を問う。書くことは、自分を理解することだ。言語化できない部分に直面したとき、私たちは「本当は理解していなかった」と気づく。だから、書くことは生きることだ。
明日から、何か一つ書いてみよう。Slackのスレッドでもいい。プルリクエストのコメントでもいい。技術記事でもいい。書こうとして手が止まる瞬間、そこに理解の穴がある。その穴を埋めることが、あなたの成長だ。
わたしにしか、書けないものは、ある。そう信じて、書き続けることだ。
