第20章テクニカルライティングと知識共有

この章では、AIコーディングの作業で生まれた情報を、チームが使える技術文書へ変える。README、設計メモ、ADR、PR説明、runbook、インシデント報告を読者と目的で使い分け、AIで整えた文章を人間が確認する流れを学ぶ。ここでは、研修の外でも通用する一般的な専門用語を解説する。

テクニカルライティング

読み：てくにかるらいてぃんぐ／technical writing
一言で言うと：技術的な事実や手順や判断を、読者が次に行動できる形へ並べ替える書き方である。
くわしく：文章をきれいに飾る技術ではない。読者が分からない前提を補い、必要な順序で情報を出し、判断の根拠を残す。文体だけを直しても文書は良くならない。読者が次に何をするかを基準に、情報の並びを設計できる。事実、判断、推測、未決定を分けることも、技術文書の正確さを支える。だから、上手な比喩よりも、読者が行動を間違えないことを優先する。
具体例：支援ステータス機能のREADMEで、起動方法と確認方法を順番どおりに書き、絞り込み条件の意味が読者に伝わるよう整える。
つまずきやすい点：文章が自然かどうかだけで評価しがちだが、読者が行動できるかを見落とすと役に立たない。
関連語：知識共有（第20章）、文書レビュー（第20章）
テキスト本文での登場箇所：第20章「エンジニアは毎日文章を書いている」

知識共有

読み：ちしききょうゆう／knowledge sharing
一言で言うと：個人が持つ調査結果や判断を、チームが後から使える形で残し共有することである。
くわしく：一回の作業記録で終わらせず、未来の開発者が同じ調査を繰り返さずに済むようにする。誰が何を頼み、どの差分を採用し、どのテストを通し、どの判断を残したかを文書へ整理する。文書は変更を支える基盤になる。チームで長くソフトウェアを扱うなら、知識共有が開発の速さと安全さを支える。一人の頭の中に閉じた情報は、その人がいなくなると失われる。
具体例：支援ステータス機能の絞り込みをなぜURLに残したのかをADRと設計メモに書き、半年後に別の開発者が読めるようにする。
つまずきやすい点：知識共有は余裕があるときの飾りだと思われやすいが、文書がないと調査が毎回やり直しになる。
関連語：テクニカルライティング（第20章）、ADR（第20章）
テキスト本文での登場箇所：第20章「エンジニアは毎日文章を書いている」

Diátaxis

読み：でぃあたくしす／Diátaxis
一言で言うと：技術文書を、チュートリアル、ハウツー、リファレンス、説明の4種類に分ける枠組みである。
くわしく：英語の名前を覚えるための分類ではない。読者が今、何をしようとしているのかを見て、情報の置き場所を決めるために使う。文書の失敗の多くは、この4つが混ざるところから始まる。READMEに4種類すべてを入れると入口文書が重くなる。厳密な箱ではないが、情報が混ざったときに気づくための道具になる。
具体例：支援ステータス機能で、起動手順はハウツー、許可されるstatus値はリファレンス、URLに条件を残す理由は説明、と置き場所を分ける。
つまずきやすい点：4つを厳密な分類として運用しようとすると窮屈になる。混ざりに気づく目安として使う。
関連語：チュートリアル（第20章）、ハウツー（第20章）、リファレンス（第20章）、説明（第20章）
テキスト本文での登場箇所：第20章「文書タイプは、情報の置き場所を決める道具である」

チュートリアル

読み：ちゅーとりある／tutorial
一言で言うと：初めて学ぶ人が、順に手を動かして成功を体験するための文書である。
くわしく：Diátaxisの4類型の一つである。読者はまだ全体を知らないため、選択肢を増やしすぎず、成功できる一本道を用意する。学習が目的なので、迷わず最後まで到達できることを優先する。途中で分岐や例外を増やすと、初学者は脱落しやすい。完了したという達成感が、次の学習へつながる。
具体例：支援ステータス機能を、ローカルでアプリを起動し、サンプルデータを見て、絞り込みを試す学習用手順としてまとめる。
つまずきやすい点：網羅性を求めて選択肢を増やすと、初学者が迷う。一本道に絞る。
関連語：Diátaxis（第20章）、ハウツー（第20章）
テキスト本文での登場箇所：第20章「文書タイプは、情報の置き場所を決める道具である」

ハウツー

読み：はうつー／how-to guide
一言で言うと：特定の作業や問題を解くための手順に集中した文書である。
くわしく：Diátaxisの4類型の一つである。読者は何を達成したいかをすでに知っている。だから文書は、その目的へ向かう手順に集中する。学習用のチュートリアルと違い、背景説明より目的達成を優先する。手順が多すぎると、目的にたどり着く前に読者が疲れる。一つの作業に対して一つのハウツーを用意すると分かりやすい。
具体例：「支援ステータス一覧で、最終更新日を指定して対象者を確認する」「ローカルでAPIの絞り込みを確認する」という作業別の手順を書く。
つまずきやすい点：背景や理由を書き込みすぎると、目的への手順がぼやける。理由は説明や設計メモへ分ける。
関連語：Diátaxis（第20章）、チュートリアル（第20章）、runbook（第20章）
テキスト本文での登場箇所：第20章「文書タイプは、情報の置き場所を決める道具である」

リファレンス

読み：りふぁれんす／reference
一言で言うと：正確な情報を引くための、事実中心の文書である。
くわしく：Diátaxisの4類型の一つである。query parameterの名前、許可される値、API responseの形、設定値、エラーコードなどが入る。読者は必要な事実を素早く探したい。ここに長い背景説明を混ぜると、読者は事実を探しにくくなる。網羅性と正確さが価値になる。
具体例：支援ステータスAPIで、許可されるstatus値、updated_from と updated_to の形式、応答の構造を一覧にして引けるようにする。
つまずきやすい点：判断理由や経緯を書き込むと、事実を引く目的を邪魔する。背景は説明やADRへ置く。
関連語：Diátaxis（第20章）、説明（第20章）
テキスト本文での登場箇所：第20章「文書タイプは、情報の置き場所を決める道具である」

説明

読み：せつめい／explanation
一言で言うと：背景や理由を理解するための、考え方を伝える文書である。
くわしく：Diátaxisの4類型の一つである。なぜその設計にしたのか、なぜその方針なのかという理解を助ける。手順を実行することよりも、読者が納得して文脈をつかむことを目的とする。判断理由は、この説明や設計メモ、ADRに置く。手順中心の文書に理由を詰め込むと両方が読みにくくなるため、置き場所を分ける。
具体例：なぜ絞り込み条件をURLに残すのか、なぜDB schemaを変えないのか、なぜ不正なstatusを500にしないのか、という理由を説明としてまとめる。
つまずきやすい点：手順文書(ハウツーやリファレンス)に理由を混ぜると、両方の読みやすさが落ちる。
関連語：Diátaxis（第20章）、設計メモ（第20章）、ADR（第20章）
テキスト本文での登場箇所：第20章「文書タイプは、情報の置き場所を決める道具である」

ADR

読み：えーでぃーあーる／Architecture Decision Record
一言で言うと：アーキテクチャ上重要な一つの判断を、小さな記録として残す文書である。
くわしく：略語の正式名称はArchitecture Decision Recordである。大きな設計書より、小さく保守しやすい記録として、文脈、決定、状態、結果を残す。設計メモが問題や選択肢を広く扱うのに対し、ADRは一つの決定だけを将来へ残す。状態として、提案中、採用、置き換え済み(superseded)、廃止などを書く。一度採用しても真理ではないので、状況が変われば新しいADRで置き換え、古いものはsupersededとして残す。
具体例：「支援ステータス一覧の絞り込み条件をURLに残す」という判断だけを、状態、背景、決めたこと、影響、選ばなかった案として記録する。
つまずきやすい点：巨大な設計書にしたくなるが、一つの重要な決定へ絞る。長い背景は設計メモへリンクする。
関連語：設計メモ（第20章）、superseded（第20章）、説明（第20章）
テキスト本文での登場箇所：第20章「ADRは、一つの重要な判断を残す」

設計メモ

読み：せっけいめも／design doc・設計文書
一言で言うと：コードを読むだけでは分からない判断の背景を残す文書である。
くわしく：コードは何をしているかを示すが、設計メモはなぜその形にしたかを示す。背景、課題、制約、選択肢、採用案、判断理由、影響、残課題を書く。特に採用しなかった案を残すと、未来の読者が同じ議論を繰り返さずに済む。すべてを美しく結論づける必要はなく、まだ決めていないことは残課題として書く。不明点を隠すと、読者は決定済みだと誤解する。
具体例：絞り込み条件をURLに残すか、サーバー側でfilterするか、不正なstatusをエラーにするかなどの判断を、選択肢と判断理由として整理する。
つまずきやすい点：結論だけを書くと背景が失われる。捨てた案と判断理由を残す。
関連語：ADR（第20章）、説明（第20章）、PR説明（第20章）
テキスト本文での登場箇所：第20章「設計メモは、判断の背景を残す」

runbook

読み：らんぶっく／runbook・運用手順書
一言で言うと：繰り返す運用作業や問題対応の手順を、安全に実行できる形でまとめた文書である。
くわしく：READMEが入口なら、runbookは運用中に開く手順である。平常時に学ぶより、何かを確認したいときや失敗を止めたいときに読まれる。前提、使ってよい条件、使ってはいけない条件、手順、確認方法、戻し方、危険な操作、エスカレーション先を書く。コマンドだけを並べると危険で、どの環境で実行し、何を確認し、期待結果は何かが分からないと、読者は実行してよいか判断できない。背景が必要なら設計メモやADRへリンクする。
具体例：「絞り込み結果がおかしいと報告されたときの確認手順」として、URLのquery parameterを確認し、検証環境で再現し、担当外データが含まれないか確認する手順を書く。
つまずきやすい点：コマンドだけを羅列すると、前提や戻し方が抜けて事故につながる。
関連語：インシデント報告（第20章）、ハウツー（第20章）、README（第5章）
テキスト本文での登場箇所：第20章「runbookは、判断中に読む文書である」

インシデント報告

読み：いんしでんとほうこく／incident report
一言で言うと：問題が起きたあとに、事実、影響、対応、原因候補、再発防止を残す文書である。
くわしく：障害から学ぶための記録で、ポストモーテム(postmortem、事後検証)と関連する。責任追及ではなく、次に同じ問題を起こしにくくする学習へ向ける。事実、推測、判断を分けて書く。事実はログや時刻など確認した情報、推測は未確定の原因候補、判断は次にどうするかである。時刻にはtimezoneを付け、影響が分からない場合は分からないと書く。action itemには所有者、期限、確認方法を持たせる。これらを混ぜると、どこまで確認済みか読者が分からなくなる。
具体例：不正な status query value で一覧画面が500になった事例で、時系列、影響範囲、起きたこと、対応、再発防止策(テスト追加やREADME追記)を残す。
つまずきやすい点：責任追及の文書にしてしまうと、原因を率直に書けず学習につながらない。
関連語：runbook（第20章）、文書レビュー（第20章）
テキスト本文での登場箇所：第20章「インシデント報告は、責める文書ではない」

PR説明

読み：ぴーあーるせつめい／PR description・pull request description
一言で言うと：レビュアーがレビューを始めるための入口となる、変更の説明文である。
くわしく：差分の目次ではない。背景、何を変えたか、何を変えていないか、どう確認したか、見てほしい点、残課題やリスクを書く。将来の履歴として読まれるため、何をしたかだけでなく、なぜその変更が必要かを伝える。説明が薄いとレビュアーは差分から背景を推測することになり、指摘が表面的になりやすい。長すぎて要点が埋もれても入口として機能しない。AIを使った場合は、どこに使い人間が何を確認したかも書く。
具体例：支援ステータスの絞り込み追加で、Summary、Changes、Not included、Verification、Review focus、AI assistance、Remaining work に分けて書く。
つまずきやすい点：差分の一覧だけを書くと背景が伝わらず、長く書きすぎると要点が埋もれる。
関連語：設計メモ（第20章）、文書レビュー（第20章）
テキスト本文での登場箇所：第20章「PR説明は、レビューの入口である」

文書レビュー

読み：ぶんしょれびゅー／doc review・document review
一言で言うと：文書が読者の次の行動を助けられるかを確認するレビュー作業である。
くわしく：誤字や表記ゆれを見るだけではない。コードレビューと同じように、文書にも品質観点がある。読者が明確か、目的が明確か、手順が再現できるか、コマンドに実行場所と期待結果があるか、判断理由があるか、事実・判断・推測・未決定が分かれているか、根拠のない追加がないか、制約や残課題が削られていないか、古くなりやすい情報が分かるか、秘密情報がないか、関連リンクがあるかを確認する。AIで文章を整えた場合は、何を採用し何を採用しなかったか、AI推敲後に何を確認したかを残すと、説明責任が果たせる。
具体例：設計メモとADRを対象に、AIに依頼した整理のうち採用した改善と採用しなかった改善を記録し、チェックリストで確認する。
つまずきやすい点：誤字探しで終えてしまうと、読者や再現性という重要な観点を見落とす。
関連語：テクニカルライティング（第20章）、PR説明（第20章）、再現性（第5章）
テキスト本文での登場箇所：第20章「文書レビューは、誤字探しだけではない」

last reviewed

読み：らすとれびゅーど／last reviewed・最終確認日
一言で言うと：その文書を最後に確認した日付を記す、文書運用の実践である。
くわしく：文書は書いた瞬間から古くなる可能性を持つ。起動コマンドが変わり、query parameterが増え、feature flagがなくなる。last reviewedがあると、読者は情報の古さを判断できる。すべての文書に重い管理は不要だが、判断や運用に使う文書では、いつ確認されたかを示すと安全になる。更新担当(owner)、正本(source of truth)、関連PRと並べて書くことが多い。AIが読むcontextとしても、古い前提を渡さないために役立つ。
具体例：READMEの Maintenance 節に last reviewed: 2026-06-25 と書き、query parameterを追加したときに見直す運用にする。
つまずきやすい点：日付を書いても更新の見直しをしないと、古い確認日が残り続けて信頼を損なう。
関連語：superseded（第20章）、文書レビュー（第20章）
テキスト本文での登場箇所：第20章「古くなる情報を管理する」

superseded

読み：すーぱーしーでっど／superseded・置き換え済み
一言で言うと：ADRなどで、より新しい判断に置き換えられた状態を示す語である。
くわしく：一度採用した判断も、状況が変われば新しいADRで置き換えられる。そのとき古いADRは消さず、supersededとして新しい判断へのリンクを残す。古い判断を消すと、過去の文脈が失われる。判断の履歴として価値がある文書は残し、置き換え先を明示する。AIが読むときも、置き換えの関係が見えないと古い判断を現在の仕様と誤解する可能性がある。
具体例：「URLに条件を残す」というADRが後に「複雑な条件は保存済みビューに移す」へ置き換えられたら、前のADRをsupersededとして新しいADRへリンクする。
つまずきやすい点：古いADRを削除すると、なぜその判断に至ったかの文脈が消える。残して置き換え先を示す。
関連語：ADR（第20章）、last reviewed（第20章）
テキスト本文での登場箇所：第20章「古くなる情報を管理する」

source of truth

読み：そーすおぶとぅるーす／source of truth・正本
一言で言うと：その情報を確認するときに最終的に戻るべき根拠元である。
くわしく：文書は便利だが、コード、schema、test、公式資料、ADRなどのどれが正本かを決めておかないと、古い説明が現在の仕様のように読まれる。READMEに使い方を書いても、APIの許可値の正本は実装やtestかもしれない。source of truthを書くと、読者は迷ったときにどこを確認すべきか分かる。AIにcontextを渡すときも、正本が見えると古い文書を現在仕様として扱う失敗を減らせる。
具体例：支援ステータスAPIのquery parameterの正本を app/api/support-statuses/route.ts と tests/support-statuses-api.test.ts としてREADMEのMaintenance欄に書く。
つまずきやすい点：READMEに書いてあるから常に正しいと思い込む。文書が古い可能性もあるため、正本とlast reviewedを見る。
関連語：last reviewed（第20章）、文書レビュー（第20章）
テキスト本文での登場箇所：第20章「古くなる情報を管理する」

事実・判断・推測・未決定

読み：じじつ・はんだん・すいそく・みけってい
一言で言うと：文書の中の情報を、確認済みのこと、決めたこと、仮説、まだ決めていないことに分ける整理である。
くわしく：技術文書では、自然な文章よりも、どこまで確認済みかが分かることが大切である。事実には実行結果やログなどの根拠がある。判断には理由と代替案がある。推測はまだ確定していない原因候補である。未決定は、誰がいつ決めるかを残す必要がある。これらを混ぜると、読者は確認済みの仕様と未確定の考えを区別できなくなる。
具体例：「API testは通った」は事実、「URL queryに条件を残す」は判断、「日付境界が原因かもしれない」は推測、「updated_to を含むか」は未決定として書く。
つまずきやすい点：AIで文章を整えると、推測や未決定が自然な断定文に変わることがある。文書レビューで確認する。
関連語：文書レビュー（第20章）、インシデント報告（第20章）
テキスト本文での登場箇所：第20章「読者、目的、読むタイミングを先に決める」

README

→第5章

再現性

→第5章。文書の文脈では、手順を読んだ別の人が同じ環境で同じ結果に到達できることを指す。READMEやrunbookでは前提、順序、期待結果を書き、文書レビューでも手順が再現できるかを確認する。

第20章 テクニカルライティングと知識共有