evergreen-technical-book

Evergreen Technical Book

中核となる視点

技術書は、長く使える原則、意思決定の枠組み、メンタルモデル、ワークフローを印刷版または安定した原稿で教え、変わりやすいコマンド、UI の操作手順、ベンダーの詳細、バージョン固有の手順を更新可能な補助資料にまとめることで、長く価値を保てます。

このスキルを使って、次のことを行います。

• 技術書に含める内容と、Web サイト、リポジトリ、ワークシート、動画、チェックリストに分ける内容を判断します。
• 抽象的にすることなく、バージョン間のずれを抑えます。
• 補助資料の更新ポリシーを設計します。
• セルフホスト、DevOps、ソフトウェア、インフラストラクチャに関する書籍を、何年にもわたって役立つものにします。
• ツールの細部を詰め込みすぎた原稿を改訂します。

参照先の案内

必要な内容	参照先
長く使える概念と用語	references/core/knowledge.md
耐久性と分割のルール	references/core/rules.md
書籍と補助資料の例	references/core/examples.md
耐久性をすばやく確認するチェックリスト	references/core/checklist.md
書籍と補助資料を分割する	workflows/split-book-and-companion.md

ワークフロー

1. 長く価値を保つ約束を明確にする

数年先も価値を保つべき読者の成果を明示します。

その約束が特定のベンダー、UI、または限られたバージョンのツールに依存する場合、その書籍を意図的に特定の版に限定するのか、それとも内容を見直すべきかを判断します。

2. コンテンツを有効期間で分類する

主要な各セクションまたは成果物に、次のいずれかのタグを付けます。

• 長く使える：概念、トレードオフ、障害モード、原則、メンタルモデル。
• 中程度の期間使える：ワークフロー、アーキテクチャパターン、チェックリスト、構成例。
• 変わりやすい：UI のクリック操作、価格、ベンダーポリシー、正確なパッケージバージョン、スクリーンショット、短命なツール。

3. コンテンツを分割する

書籍は具体的な内容を保ちつつ、すぐに古くなるおそれのある変わりやすい詳細は補助資料に移します。

アップセルや非公開の資料、壊れやすいリンクに頼らなくても、書籍だけで中核となる約束を果たせるようにします。

4. 補助資料を設計する

補助資料ごとに、次の項目を定めます。

• 目的。
• 担当者。
• 更新のきっかけ。
• 安定した URL またはリポジトリ内のパス。
• バージョンまたは最終確認日の記載。
• 変更があっても参照先が無効にならないよう、書籍内で参照する方法。

5. 更新の仕組みを加える

保守計画を作成します。

• バージョン管理されたサンプル。
• 変更履歴または最終確認日。
• 読者向けの課題報告先。
• 定期的な見直しの頻度。
• 古くなったツールの置き換えポリシー。

出力形式

長く使える技術書について支援する場合、次の内容を返します。

1. 耐久性の診断。
2. 書籍と補助資料の分割表。
3. 推奨する範囲の削減または移動。
4. 補助資料の計画。
5. 更新ポリシーと見直しの頻度。
6. 変わりやすい参照先に関する原稿の文案。

品質基準

内容を曖昧にして、情報のずれを解決しようとしないでください。変わりやすい詳細を更新しやすく、古くなったときに参照を省きやすくしながら、読者が進む道筋は具体的に保ちます。