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

Slide 01. テクニカルライティングと知識共有

第20章では、テクニカルライティングと知識共有を扱います。ここでの目的は、文章をきれいに見せることではありません。実装した機能について、設計意図、使い方、判断理由、運用上の注意、残課題を、チームがあとから読める形で残すことです。技術文書は、チームでソフトウェアを作り続けるための成果物です。

Slide 02. この章で持ち帰ること

この章で持ち帰ってほしいことは三つです。一つ目は、文書を書く前に読者と目的を決めることです。二つ目は、README、設計メモ、ADR、runbook、障害報告を使い分けることです。三つ目は、AIで文章を整えても、内容が正しいか、根拠があるか、未実行確認をごまかしていないか、秘密情報が混ざっていないかを人間が確認することです。

Slide 03. 第19章との接続

第19章では、AIコーディングの流れとして、何を作るかのメモ、AIに渡す情報、作業計画、差分レビュー、作業ログ、PR説明を作りました。第20章では、その情報をチームの知識として残します。AIで速く作れても、判断理由や使い方が残っていなければ、レビュー、引き継ぎ、保守、障害対応で困ります。

Slide 04. エンジニアは毎日文章を書く

エンジニアは、コードだけを書いているわけではありません。PR説明、コメント、README、設計メモ、障害報告、運用メモを書きます。技術文書がないと、同じ質問、同じ調査、同じ議論が繰り返されます。AI時代には、AIに渡す前提情報としても文書の価値が上がります。文書は補助作業ではなく、実装をチームで使い続けるための一部です。

Slide 05. 読者を決める

文書は、誰が、いつ、何をするために読むかで形が変わります。新しく参加した開発者、レビュアー、運用担当、未来の自分では、必要な情報が違います。すべての読者に向けた文書は、誰にも使いにくくなりがちです。書き始める前に、読者、目的、読むタイミングを決めましょう。

技術文書では、事実、判断、推測、未決定を分けます。テストが通った、という事実にはコマンド結果があります。URLに条件を残す、という判断には理由と代替案があります。原因かもしれない、という推測は推測として書きます。まだ決めていないことは、誰がいつ決めるかを書きます。この分け方があると、AIで文章を整えた後も、根拠のない断定に気づきやすくなります。

Slide 06. 文書タイプを分ける

文書タイプを混ぜないことも大切です。学ぶために順番に進む文書、困りごとを解く手順、仕様を調べる一覧、背景や判断理由を読む説明では、書く内容が変わります。英語では tutorial、how-to、reference、explanation と呼ぶことがあります。ここでは名前を覚えるより、読者が何をしたいかで分けることを押さえます。

Slide 07. README

READMEは、リポジトリや機能の入口です。何のためのものか、どう動かすか、どう使うか、どう確認するか、どこを見ればよいかを書きます。セットアップ手順には、前提、実行場所、実行順序、期待結果を書きます。既知の制約や未対応も隠しません。READMEは説明文ではなく、読者が最初に作業を始めるための道具です。

Slide 08. 設計メモ

設計メモは、なぜこの形にしたかを残す文書です。背景、問題、制約、根拠、選択肢、判断、影響、残課題を書きます。実装済みのコードだけでは、なぜそうしたかが分からないことがあります。AIに実装させた場合も、人間が判断理由を整理します。設計メモは唯一の正解だと言う文書ではなく、判断をレビューし、将来の変更に備える文書です。

Slide 09. ADR

ADRは Architecture Decision Record の略で、大事な技術判断と理由を残す短い記録です。1つのADRでは、1つの判断だけを扱います。状態、背景、決めたこと、良い影響、悪い影響、中立の影響、選ばなかった案を書きます。判断が変わったら、過去を書き換えず、新しいADRで前の判断を置き換えたことを書きます。英語の項目名は、テンプレートで確認できれば大丈夫です。

Slide 10. PR説明

PR説明は、レビューの入口です。何を変えたか、なぜ変えたか、どう確認したか、何を確認していないか、どこを見てほしいかを書きます。大きな差分をそのまま出すだけでは、レビュアーの負担が大きくなります。スクリーンショット、API例、テスト結果、残課題があるとレビューしやすくなります。AIを使った場合も、手で確認した点を簡潔に書きます。

Slide 11. runbook

runbookは、繰り返す運用作業や障害時の手順を残す文書です。前提、使ってよい条件、使ってはいけない条件、手順、確認方法、失敗時の戻し方を書きます。コマンドには、実行場所、対象環境、期待結果を書きます。危険な操作には注意を書きます。知っている人だけができる作業を、チームで再現できる作業に変えるための文書です。

Slide 12. 障害報告

障害報告では、何が起きたか、影響、時系列、対応、原因候補、再発防止を分けます。時刻にはタイムゾーンを入れます。事実、推測、判断を混ぜないようにします。誰かを責める文章にしません。次にやる対応項目には、担当者、期限、確認方法を持たせます。障害報告は謝罪文でも犯人探しでもなく、再発を減らし、チームが学ぶための文書です。

Slide 13. 良い文書の条件

良い技術文書は、読者が次の行動を取れる文書です。新しい開発者なら起動できる。レビュアーなら判断理由と確認結果を追える。運用担当なら手順と戻し方が分かる。未来の自分なら、なぜその判断をしたか思い出せる。文書の品質は、文章の美しさだけではなく、読者の行動を助けるかで判断します。

Slide 14. 短さより必要十分

短い文書がいつも良いとは限りません。読者が必要な判断や作業をできるだけの情報が必要です。ただし、同じ情報の重複、古い情報、関係ない背景は減らします。重要なことから書き、詳細は見出しで分けます。省きすぎて読者が迷う文書も、詰め込みすぎて読めない文書も、どちらも使いにくくなります。

Slide 15. 見出しと構造

技術文書は、上から全部読まれるとは限りません。見出し、箇条書き、表、コードブロックを使って、必要な場所を見つけやすくします。背景、手順、判断、注意、関連リンクを分けます。長い文章でつなげるより、読者が必要な場所へすぐ行ける構造にします。構造は、読みやすさだけでなく、更新しやすさにも効きます。

Slide 16. README更新例

支援ステータス一覧の絞り込み機能なら、READMEには、機能概要、使い方、動作確認、設定変更、制約、関連文書を書きます。たとえば、ステータスで絞り込むと該当ステータスの受講者だけ表示される。最終更新日で絞り込むと指定日以降の更新だけ表示される。条件を解除すると通常表示に戻る。読者が確認できる形にします。

Slide 17. 設計メモ例

設計メモでは、なぜ絞り込み機能が必要か、どんな制約があったか、どんな選択肢を検討したかを書きます。たとえば、URLに絞り込み条件を残す案、画面の中だけで条件を持つ案、DBの形を変える案を比較します。採用した案、判断理由、画面、API、DB、テスト、運用への影響、残課題を残します。

Slide 18. ADR例

ADRでは、重要な判断を一つに絞ります。たとえば、支援ステータス一覧の絞り込み条件をURLに残す、という判断です。状態には提案中か採用済みか。背景には、なぜ決める必要があったか。決定には、選んだ案。影響には、良い点と注意点。選ばなかった案も短く残します。

Slide 19. 障害報告例

必要に応じて、障害報告の下書きも整えます。英語の見出しを覚えるより、まずは概要、影響、時系列、対応、原因候補、次にやる対応を分けます。たとえば絞り込み条件の不具合で一覧が空に見えたなら、誰にどれくらい影響したか、いつ気づいたか、どう戻したか、次に何を変えるかを書きます。

Slide 20. AIで文章改善

AIは、構成案、要約、表現改善、読み手別の書き換え、レビュー観点の洗い出しに使えます。ただし、AIに短くしてとだけ頼むと、重要な判断理由や制約まで削ることがあります。読者、目的、残すべき情報を指定しましょう。AIは文章を整える相手になりますが、文書の責任と正確性は人間が持ちます。

Slide 21. AI利用時の注意

AIに文書を渡す前に、APIキーなどの秘密情報、個人情報、未公開情報を取り除きます。改善案を採用する前に、技術的な事実を勝手に足していないか、判断理由や制約を削っていないか、未決定事項を断定に変えていないかを見ます。共有する前に、根拠と機密情報をもう一度確認します。AIで整えた文章でも、最後に責任を持つのは人間です。

Slide 22. 文書レビュー

技術文書もレビューします。見るのは誤字だけではありません。読者が明確か。目的が明確か。手順が再現できるか。コマンドに実行場所と期待結果があるか。判断理由があるか。古い情報や矛盾がないか。公開リポジトリに出せない情報がないか。AIに渡す前提情報として使えるか。完璧な文書を一回で作るより、チームで更新し続けられる文書を目指します。

Slide 23. 古くなる文書

技術文書は古くなります。だから、誰が見直すか、いつ見直すか、最後に確認した日、正本、関連するPRを書いておきます。古い可能性がある文書は、その状態を示します。コードから自動生成できる情報と、人間が判断して書く情報を分けます。不要になった文書を削除する判断も必要です。文書はコードと同じように見直す対象です。

Slide 24. 知識共有

知識共有は、引き継ぎのためだけではありません。新しく入った人の立ち上がり、レビュー、運用、障害対応、AIに渡す前提情報の品質にも効きます。文書があると、その場で集まる会議や口頭説明を減らせることがあります。書くことで、自分の理解の穴も見つかります。人の頭の中だけにある知識を検索できる形にすることが、開発速度と安全性を支えます。

Slide 25. 個人開発課題への接続

次の個人開発課題では、作ったプロダクトを他の人が理解し、起動し、レビューできる状態にします。ここで作るREADME、設計メモ、ADR、文書レビューの考え方は、第21章のproject brief、MVPスコープ、レビュー依頼にもつながります。動くものだけでなく、誰に向けたものか、どう確認したか、なぜそう作ったかを説明できる状態にします。

Slide 26. Exercise 1

一つ目の演習では、読者と文書タイプを整理します。最低限、誰が、いつ、何を知りたいかを書きます。余裕があれば、README、設計メモ、ADR、runbook、障害報告のどれが必要か、どの文書が正本か、誰が見直すかも判断します。たとえば、新しく参加した開発者、レビュアー、将来の開発者、運用担当に分けて考えます。成果物は doc-audience-plan.md です。

Slide 27. Exercise 2

二つ目の演習では、README更新案を書きます。最低限、機能概要、使い方、動作確認、制約を書きます。動作確認には、実行場所、操作またはコマンド、期待結果を入れます。余裕があれば、設定変更、関連文書へのリンク、Maintenanceも足します。支援ステータス一覧の絞り込み機能について、読者が実際に使い、確認できる形にします。成果物は readme-update-draft.md です。

Slide 28. Exercise 3

三つ目の演習では、設計メモを書きます。最低限、背景、課題、採用した案、判断理由、残課題を書きます。余裕があれば、制約、根拠、選択肢、影響、未決定事項、関連PRやADRも足します。実装の見た目だけでは分からない判断理由を、将来の開発者が追えるようにします。成果物は feature-design-note.md です。

Slide 29. Exercise 4

四つ目の演習では、ADRを書きます。重要な判断を一つ選び、状態、背景、決めたこと、良い影響、悪い影響、中立の影響、選ばなかった案、関連リンクを整理します。最低限、判断を一つに絞り、なぜ選んだかを書ければ大丈夫です。たとえば、支援ステータス一覧の絞り込み条件をURLに残す、という判断です。成果物は adr-0001-filtering-support-status.md です。

Slide 30. Exercise 5

五つ目の演習では、AIで文章を改善し、文書レビューを行います。最低限、AIに何を依頼したか、どの改善を採用したか、どれを採用しなかったか、残課題を書きます。AI推敲後に、事実の追加、判断理由の削除、未決定事項の断定、secret混入がないかも確認します。余裕があれば、レビュー観点をチェックリストにし、障害報告の下書きも整えます。成果物は doc-review-note.md です。

Slide 31. 第21章への接続

次の第21章では、自由テーマの個人開発プロジェクトを始めます。第20章で練習した書き方は、project brief、MVPスコープ、README、レビュー依頼にそのまま使います。誰に向けたプロダクトか、どう動かすか、なぜその設計にしたか、どうレビューしてほしいか。これらを説明できる状態で、実際の開発課題へ進みましょう。