writing-runbooks

ランブックの書き方

必須の前提: technical-writing スキル (厳格なルール、真実性のルール、スタイル)。

概要

読者は急いでおり、多くの場合インシデントの最中です。すべてのランブックは順序立てられ、1ステップにつき1つのアクションで、コピー&ペーストでき、危険が読者の目にすでに入るところに明示されています。

実際の実行から書いてください。すべてのステップは実際に行われたもの、すべての障害は実際に起きたものが名指しされます。机の上で想像された手順はドラフトであり、ランブックではありません。部分的にしか実行されていない手順は、分岐ごとの誠実さをもって公開してもかまいません。まだ実行されていないバリアントを名指しし、その分岐をドラフトと明示し、最初の実際の実行者に報告を依頼してください。どの分岐にも実際の実行が伴わない手順は、そもそもドラフトです。コマンドが必要とする値が本当に不明な場合は、プレースホルダーを目に見える形で角括弧に入れたままにし、決してでっち上げず、公開前に実際の実行から埋めてください。真実性はコピー&ペーストのしやすさより優先されます。

いつ呼び出すか、呼び出さないか

人が実行するものすべてに対して呼び出してください。ランブック、セットアップおよびリリース手順、トラブルシューティングの項目、運用チェックリスト、システム内のオペレーター向け文字列などです。設計の根拠 (writing-design-docs) や、誰も実行しない参照資料に対しては呼び出さないでください。手順が一度も実行されていない場合は、まず実行するか、その文書をドラフトとラベル付けしてください。テストされていない手順をランブックとして公開することこそが欠陥であり、ラベル付けの問題ではありません。

構成

• タイトルにはスコープを含めます:「MVP ランブック (Reddit)」、「リリースランブック」。
• この文書が兄弟文書に対して何であるかを冒頭で述べ (「この文書は順序であり、各ステップの詳細は X にあります」)、この文書が扱わないことを明示します。
• ステップごとにリスクが異なる場合は、冒頭に凡例を置き、すべてのコマンドに適用します: いつでも実行して安全 / オペレーター専用 (本番環境への書き込み) / ターミナル外での手動ステップ。ステップが複数の性質を持つ場合はタグを組み合わせます。
• まず TL;DR のハッピーパス、次に同じステップを番号付きセクションとして、1つだけ必要な読者向けに示します。
• コマンドの前に、バージョンを固定した前提条件を置き、それぞれに確認コマンドを付けます。
• 番号付きの序数ステップ (箇条書きではない)、それぞれ1つのアクション、現在形または命令形で、行為者を明示します。
• すべてのコマンドはそのままコピー&ペーストでき、具体的な例の値を付けます (「よくあるパス: /public_html/、/www/」)。コードブロック内でバリアントにラベルを付けます:

# safe mode
app sync run --channel=reddit --limit=100

# live mode (writes to the provider)
app sync run --live --approval-token=...

• 順序付きステップでは、順序を誤った場合の結果をその場で述べます: 「jar をデプロイしてから DB クリーンアップ。順序を誤ると無言のデータ損失になります。」
• 状態を変更するすべての手順は、そのロールバックを名指しするか、存在しないこととそれが何を意味するかを率直に述べます。
• 最後に「動作を確認する」セクションを置きます: 観察可能な最終状態と、それを証明するコマンドです。
• 複数のパスが存在する場合は、推奨するパスに「(推奨)」を付けます。同じタスクの UI とコマンドラインは、二度書くのではなく並べて記載します。
• ツールが導入されるとランブックが短くなる場合は、そう述べます: 「X が導入されると、ステップ 2 から 4 は1つのコマンドになり、この文書には判断のみが残ります。」

トラブルシューティングの項目

症状を先に:

## <symptom as the user sees it>
**Symptom**: verbatim error strings (searchable)
**Cause**: ...
**Fix**: exact commands

診断ステップは最も安価なものから順に並べます。項目は障害クラスごとにグループ化します。深い文書はインライン化せず、相互リンクします。

移行ガイドと非推奨化ガイド

移行ガイドとは、変更そのものを主題とするランブックです。前述のすべてが当てはまりますが、さらに独自の 5 つのルールが加わります。移行の根拠は設計ドキュメント（writing-design-docs）、非推奨化の決定は ADR（recording-decisions）、告知は変更履歴のエントリ（writing-changelogs）です。本セクションでは、読者が実行するガイドのみを扱います。

1. ここでは履歴が内容そのものであり、肯定的に記述します。 before/after の比較はこの作業の目的であり、違反ではありません。これは、履歴を書かないというハードルールが明示的に例外とするドキュメント種別です。「タグは手動のバージョンアップを置き換えるようになりました」と自由に書いてかまいません。この文は他のどこでも禁止されていますが、ここでは不可欠です。
2. マッピングテーブルが中核となる成果物です。 動作、設定キー、コマンド、API ごとに旧から新へ、それぞれ 1 行ずつ記載します。散文は説明が必要な行を補足し、移行そのものはテーブルが担います。
3. ロールバックは必須であり、ステップごとに示します。 各ステップはその取り消し方法を明記するか、不可逆であることと、それが前後の順序にとって何を意味するかを率直に述べます。
4. 非推奨化の契約には日付を伴わせます。 何がいつ動かなくなるか、未対応のものはどうなるか、それまで逃げ道がどこにあるかを示します。「将来のリリースで削除される予定です」は日付を明示しておらず、ここでは禁止です。
5. 誕生と同時に有効期限を持たせます。 移行が完了したら、オーナーはガイドを履歴扱いに再分類し、現状のドキュメントを指す「superseded」バナーを追加します。決して黙って削除しません。完了条件はガイド自体に記載します。

オペレーター向けの文字列

エラーメッセージとログ行は、最も短い閲覧時間で読まれるランブックの散文です。修復手順は具体的で実行可能に保ち、ワークフローが正常に見えてしまわないよう、エラー状態を可視化してください。