私の文章を書くとき、私は常に2つの 3つのセットを書くことに専念してきました。準備完了チェックリスト。システムのアーキテクチャに関する付録が非常に長いもので、その理由としては、物事がそのままの状態で行われる理由、オンラインになったときのスティッキングポイント、抽象的な設計の仮定などがあります。続いて、問題の可能性とその解決策のリスト、システムの動作方法、その理由、その他のユニークな何かが起こった場合に正しい方向に人々を向けるのに役立つ情報に関する長いセクションが続きます。
私の最後の仕事では、レベル1のヘルプデスクの人々でさえも物事を取り戻すことができるように、ドキュメントを書く必要がありました。これにはチェックリストが必要でしたが、通常は執筆から3か月以内に期限切れになりました。可能な限りトラブルシューティングガイドを作成することを強くお勧めしますが、コンティンジェンシーツリーに3つ以上のブランチが含まれる場合は、抽象化せずにドキュメントを作成することはできません。
私が最後の仕事を辞めるとき、私は辞める前に100ページの「仕事のやり方」マニュアルを提出しました。抽象要素、設計哲学、統合ポイントが含まれていました。私はおそらく私に代わる別のシステム管理者のために書いていたので、抽象的な概念を取り入れて具体的な行動に変えることができる誰かを目指しました。
5年が経ちましたが、これについての私の意見はいくぶん変わっています。どちらのマニュアルなどのドキュメントやチェックリストなどの文書は、文書の階層構造と製造されるべき両方を必要としている非常に貴重な場所を持っています。ただし、非常に異なるオーディエンスを対象としています。
チェックリストとして文書化
この種のドキュメントの対象市場は、物事のやり方を知りたい同僚です。次の2つのタイプがあります。
- 物事のやり方を知りたいだけで、15ページのマニュアルに目を通し、自分で手順を理解する時間がない同僚。
- 手順はかなり複雑ですが、たまにしか実行する必要がない手順。
焦りは、第一種のドライバーです。同僚は、出力を90文字のperl正規表現でパイプ処理する必要がある理由を実際に知りたくないかもしれません。ただ、チケットを閉じるために必要なだけです。理由を知りたい人のためのチェックリストに、「このワークフローがこのように見える理由の詳細な説明については、このリンクに従ってください」のようなステートメントを明確に含めてください。
2番目のポイントは、頻繁に実行されるわけではないが、落とし穴が含まれる手順です。チェックリストはマップとして機能し、特定の運命がただ翼を振るうのを避けます。チェックリストがドキュメントリポジトリに保存されていると、古い管理者がHOWTOを送信した時間を電子メールで検索する必要がなくなります。
私の意見では、優れたチェックリスト文書には、考えられる障害ポイントに関するセクションとそれらの障害への対応も含まれています。これにより、ドキュメントがかなり大きくなり、同僚のTL; DR応答がトリガーされる可能性があるため、失敗モードとその応答をページ自体ではなくチェックリストからのリンクにすると、恐ろしいチェックリストになることがわかります。ハイパーテキスト性を受け入れます。
マニュアルとして文書化
この種のドキュメントの対象市場は、システムがどのように機能するかについて詳しく知りたい人です。How-to-a-thingスタイルのドキュメントは、このドキュメントから派生できるはずですが、より一般的には、ワークフローで行われた決定をバックアップするためのチェックリストスタイルのドキュメントの補足と考えています。
これは、次のような歯ごたえのある部分を含むドキュメントです。
- このように構成されている理由の説明。
- このセクションには、全体の購入およびインストール方法に関する政治のような非技術的な問題が含まれる場合があります。
- 一般的な障害モードとその応答の説明。
- 書面および事実上のサービスレベル契約の説明。
- デファクト：「これが決勝週に失敗した場合、それはすべての問題です。夏休み中に眠りに戻り、午前中に対処します。」
- アップグレードとリファクタリングの目標を設定します。
- 政治は後で異なるかもしれませんが、最初に導入した悪い考えのいくつかを修正してみませんか？
これらはすべて、システム全体の包括的な理解を得るために非常に役立ちます。単純な人間の自動化タスクを実行するために包括的な理解は必要ありません。なぜそれが失敗したのかを理解し、それを再度行わないようにするためのアイデアが必要です。
また、チェックリストである必要がある災害復旧のドキュメントにも言及しました。
あなたは私の同情を持っています。
はい、DRのドキュメントは可能な限りチェックリストのようにする必要があります。
はい、DRのドキュメントは、物事が壊れる方法がいくつあるため、チェックリストに最も耐性があります。
DRチェックリストが次のような場合：
- ダスティンまたはカレンに電話してください。
- 問題を説明してください。
- 立ちなさい。
問題があります。これはチェックリストではありません。つまり、このシステムの復旧は非常に複雑であるため、設計者は把握する必要があります。できることはそれだけですが、可能な限り避けてください。
理想的には、DRのドキュメントには、いくつかの異なる事項の手順チェックリストが含まれています。
- トリアージの手順は把握するものを識別しやすくなる、間違っていました...
- 特定の障害の場合の復旧手順。によってサポートされています...
- 回復中の人的エラーを最小限に抑えるために、事前に十分に記述された回復スクリプト。
- 失敗事例、それらが発生する理由、およびその意味に関するマニュアル形式のドキュメント。
トリアージ手順は、一部のシステムで作成できるすべてのDRドキュメントである場合があります。しかし、それがあれば、午前4時の呼び出しがよりわかりやすくなり、リカバリーを行うシニアエンジニアは実際の問題をより迅速に解決できるようになります。
一部の障害事例には、簡単な回復手順があります。それらを文書化します。それらを文書化する際に、コマンドのリストが特定の順序で入力されている場合があります。これは、スクリプトの優れたユースケースです。96ポイントの回復手順を20ポイントの手順に変えることができます。回復手順をアクションごとにマップするまで、何かをスクリプト化できるかどうかはわかりません。
障害事例のマニュアル形式のドキュメントは、復旧手順がない場合、または復旧手順が失敗した場合に使用される最後の溝バックストップです。おそらく、その問題を抱えた他の誰かを見つけるために必要なgoogle-hintsと、それを修正するために何をしたかを提供します。