ドキュメントAs-A-ManualとドキュメントAs-A-Checklist
私は過去に、ドキュメント、特に詳細レベルと要件について、私の部門の他の人々と話し合ったことがあります。彼らの見解では、ドキュメンテーションは、Xの問題が発生したときに行うYの問題の簡単なチェックリストです。
同意しません。これは、ITのすべての問題が、回復手順の簡単なチェックリストに簡単に要約できることを前提としていると思います。それは状況の複雑さを完全に無視していると思います、そして部門の他の人々は常に問題について深い理解を持っているわけではないので（それが私がドキュメントを書いている理由です-彼らは参照する何かを持っています）ドキュメントには、次のような基本的な背景資料を含める必要があります。
- 問題の（サブ）システムの目的
- なぜそのように構成されているのか
- 設定/手順が実装されたときに発生するイベントの期待
- 手順が失敗する原因となる可能性のある問題
しかし、私はこれにかなり熱心なので、私のドキュメントは必須「手順A-B-Cを順番に適用すると問題Xが解決する」という形式に書き直されます。 1ページの紙に収まる必要があるという嘆きをよく耳にします。この方法で、トラブルシューティングを含め、1ページのドキュメントを通じてSquidACLの構成を誰かに説明してみてください。これは、リカバリチェックリストとして「書き込まれるのを待っている」半ダースのドキュメントの1つにすぎません。
私が提唱している方法は本当に行き過ぎですか？それとも彼らは正しいので、私はここで私のビジネスを気にし、簡単なチェックリストを書くべきですか？私の懸念は、手順のチェックリストをどれだけ上手に作成しても、SysAdminが物事を熟考する必要がある問題を実際には解決しないということです。問題を解決できない回復手順のチェックリストを作成することに時間を費やしている場合（ドキュメントの一部ではない追加の要因があるため、ドキュメントの焦点が狭いため ）、そしてこのドキュメントの目的は、manページ、wiki、およびWebサイトを何度も読み直さないようにすることでしたが、なぜ私は動きを経験しているのでしょうか。心配しすぎですか、それとも本当の問題ですか？
編集：
現在、部門にはヘルプデスクのポジションはありません。ドキュメントの対象読者は、他の管理者または部門長です。
私を書くとき、私はいつも書くことに専念してきました 二 3セット。やり遂げるチェックリスト、 システムのアーキテクチャについては、なぜそのように行われるのか、オンラインになったときの問題点、抽象的な設計の前提など、はるかに長い付録が付いています。 続いて、考えられる問題とその解決策のリストが続き、システムがどのように機能するか、なぜそのように機能するのか、および何かユニークなことが起こった場合に人々を正しい方向に向けるのに役立つその他の情報を含む長いセクションが続きます。
私の最後の仕事では、レベル1のヘルプデスクの人々でさえ物事を元に戻すことができるようにドキュメントを書く必要がありました。これにはチェックリストが必要でしたが、通常、執筆から3か月以内に古くなっていました。可能な限りトラブルシューティングガイドを作成することを強くお勧めしますが、緊急時対応ツリーに3つ以上のブランチが含まれている場合、抽象化せずにそのドキュメントを作成することはできません。
leaving私の最後の仕事をしたとき、私は去る前に100ページの「仕事のやり方」マニュアルを提出しました。そこには抽象的なもの、設計哲学、そして統合ポイントが含まれていました。私はおそらく私に取って代わろうとしている別のシステム管理者のために書いていたので、抽象的な概念を取り、それらを具体的な行動に変えることができる誰かを目指しました。
5年が経ちましたが、これに対する私の意見は少し変わったと思います。 マニュアルとしてのドキュメントとチェックリストとしてのドキュメントの両方が、ドキュメントの階層と両方を作成する必要があります。ただし、ターゲットは非常に異なります。
チェックリストとして文書化
この種のドキュメントのターゲット市場は、物事をどのように行うかを望んでいる同僚です。それらには2つのタイプがあります。
- 物事のやり方を知りたいだけで、15ページのマニュアルに目を通し、自分で手順を理解する時間がない同僚。
- ステップがかなり複雑であるが、たまにしか実行する必要がない手順。
焦りは第一種の原動力です。たぶんあなたの同僚は実際には知りたくないでしょうなぜ出力は90文字のPerl正規表現を介してパイプされなければならないだけですチケットを閉じます。理由を知りたい人のために、チェックリストに「このワークフローがこのように見える理由の詳細な説明については、このリンクをたどってください」のようなステートメントを必ず含めてください。
2番目のポイントは、頻繁には実行されないが落とし穴が含まれているプロシージャです。チェックリストは、単にそれを翼にするという特定の運命を回避するためのマップとして機能します。チェックリストがドキュメントリポジトリに保存されていると、古い管理者がHOWTOを送信したときにメールを検索する必要がなくなります。
私の意見では、goodチェックリスト-ドキュメントには、考えられる障害点とそれらの障害への対応に関するセクションも含まれています。これにより、ドキュメントがかなり大きくなり、同僚でTL; DR応答がトリガーされる可能性があるため、障害モードとその応答をページ自体ではなくチェックリストからのリンクにすると、怖くないチェックリストになることがわかりました。ハイパーテキスト性を受け入れる。
マニュアルとして文書化
この種のドキュメントのターゲット市場は、システムがどのように機能するかについてもっと知りたい人です。ハウツースタイルのドキュメントは、このドキュメントから派生できるはずですが、より一般的には、ワークフローで行われた決定をバックアップするためのチェックリストスタイルのドキュメントの補足と見なします。
これは、次のような歯ごたえのある部分を含むドキュメントです。
- このように構成されている理由を説明します。
- このセクションには、すべてのものを購入してインストールする方法を取り巻く政治など、技術以外の問題が含まれる場合があります。
- 一般的な故障モードとその対応について説明します。
- 書面と事実の両方のサービスレベルアグリーメントの説明。
- 事実上：「これが決勝週の間に失敗した場合、それはすべてが落ちる問題です。夏休みの間に、眠りに戻って、朝にそれに対処してください。」
- アップグレードとリファクタリングの目標を設定します。
- 後で政治が違うかもしれませんが、最初に紹介した悪い考えのいくつかを修正してみませんか？
これらはすべて、システム全体を包括的に理解するのに非常に役立ちます。単純な人間の自動化タスクを実行するために包括的な理解は必要ありません。何かがそのように壊れた理由を理解し、それを二度と行わないようにする場所を考え出す必要があります。
また、チェックリストでなければならないディザスタリカバリのドキュメントについても言及しました。
ご理解のほどよろしくお願いいたします。
はい、DRドキュメントは可能な限りチェックリストのようにする必要があります。
はい、DRドキュメントは、問題が発生する可能性のある方法がいくつもあるため、チェックリストに対して最も抵抗力があります。
DRチェックリストが次のようになっている場合：
- ダスティンまたはカレンに電話してください。
- 問題を説明してください。
- 後ろに立ちなさい。
問題があります。これはチェックリストではありません。つまり、このシステムの回復が非常に複雑で、アーキテクトが理解する必要があることを認めています。時にはそれがあなたにできるすべてですが、可能な限りそれを避けるようにしてください。
理想的には、DRドキュメントには、いくつかの異なることに関する手順チェックリストが含まれています。
- 把握するためのトリアージ手順whatがうまくいかなかったため、特定に役立ちます...
- 特定の障害の場合の回復手順。これはによってサポートされています...
- リカバリ中の人的エラーを最小限に抑えるために、事前に十分に作成されたリカバリスクリプト。
- 障害のケース、発生する理由、およびその意味に関する手動形式のドキュメント。
トリアージ手順は、一部のシステム用に作成できるすべてのDRドキュメントである場合があります。しかし、それがあるということは、午前4時のコールアウトがより理解しやすくなり、復旧を行う上級エンジニアが実際の問題をより早く解決できるようになることを意味します。
一部の障害ケースには、簡単な回復手順があります。それらを文書化します。それらを文書化していると、コマンドのリストが特定の順序で入力されている場合があります。これは、スクリプトの優れたユースケースです。 96ポイントの回復手順を20ポイントの回復手順に変えることができます。回復手順のアクションをアクションごとにマップするまで、何かをスクリプト化できるかどうかはわかりません。
障害の場合の手動形式のドキュメントは、回復手順がない場合、または回復手順が失敗した場合に使用される最後の溝のバックストップです。それはおそらくその問題を抱えている他の誰かを見つけるために必要なグーグルのヒントと彼らがそれを修正するために何をしたかを提供します。
実際にはどちらも使用しませんDocumentation As-a-Testcase
そうは言っても、Documentation As-a-Manualに付随するドキュメントを作成しました。チェックリストは用意されていましたが、成長するとエラーが発生しやすく、システム全体で実際に失敗することがわかりました。
ただし、種類の「DocumentationAs-a-Checklist」がインストールされています。つまり、前述のように、サービスを広範囲に監視しています。ことわざがあります：
あなたがそれを監視していないなら、あなたはそれを管理していません
それは完全に真実ですが、もう1つは次のようになります。
あなたがそれを監視していないなら、あなたはそれを文書化していない
サービスを移行する必要があるときはいつでも、「サービスグループ」、「ホストグループ」、該当するもの（語彙から推測できるようにNagiosを使用）を開いたままにし、赤い点が1つある限り移行されません。いずれかのサービスで。
テストは、手書きのチェックリストよりもはるかに優れたチェックリストを提供します。実際には自己文書化です。監視されていない障害が発生するとすぐに、テストは少なくともNagiosに追加され、2つのものが無料で入手できます。
- いつ失敗するかわかります
- チェックリストの別のポイント
「実際の」ドキュメントは、特定のサービスまたはテストのオッズと終了について言及しているWikiに保存されています。不足している場合は、移行や作業が必要になるとすぐに追加されます。これまでのところ、このアプローチは非常にうまく機能しています。
また、誤ったドキュメントは非常に迅速に解決されます。何かが失敗するたびに、人々はドキュメントを調べ始め、そこにあるHowTosの問題を解決しようとします。間違っている場合は、調査結果で更新してください。
チェックリストに従い、適用後に緑色のチェックボックスが表示されるテストをインストールしなかった場合に発生する可能性のあるエラーについて考えてみてください。ドキュメントをモニタリングから分離することは不可能だと思います。
それはあなたのドキュメンテーションの対象読者に依存します。
ヘルプデスク（レベル1）タイプの場合、チェックリストが正しい方法です。もちろん、これはあなたが説明するより深い知識でより高いレベルのサポートがあることを前提としています。
ドキュメントがシステムグループ向けである場合、私は常により多くのドキュメントの側で誤りを犯します。誰か（あなた自身）が必要な背景情報を含むより広範なドキュメントを書きたい場合、ただ通り抜けるために適切なドキュメントを用意するのは十分に難しいです-正気の人があなたの邪魔をするべきではありません！
個人的には、ドキュメントをできるだけシンプルに保つようにしています。これには次のものが含まれる傾向があります。
- [X]が行うことになっていること（要件）。
- [X]が高レベルでどのように構成されているか（設計）。
- [X]を自分のやり方で実装した理由（実装に関する考慮事項）。
- [X]の実装が非標準である方法（回避策）。
- [X]の一般的な問題とその解決方法（問題）。
確かに、私の一般的な問題のセクションは、何が起こったのかについての簡単な説明と、それを修正する方法についてのドットポイントのウォークスルーである可能性があります。
私は通常、問題のシステムの読者からある程度の知識があると思います（特に難解な場合を除く）。技術文書のレベル1または管理を読みやすくする時間がありませんが、手がかりのレベル3で十分です。
明らかにトピック次第だと思います。すべてを単純なチェックリストにまとめることができるわけではなく、すべてに詳細なユーザーマニュアルが必要なわけでもありません。
確かに、内部ドキュメントについて話しているように聞こえます。私の経験では、選択肢が多すぎるため、手順のリストを提供することはできません。ユーザーアカウントを作成する場合でも（私たちの環境では）いくつかのオプションがあるため、「新しいアカウント」ドキュメントには基本的な手順が順番に記載されていますが、各手順にはバリエーションの説明があります。
一方、「オフィスでパッチを当てる方法」のドキュメントの多くを書くことはできませんでしたが、非常に大ざっぱなドキュメントもチェックリストではありませんでした。ケーブルの色に使用した規則について説明し、強調しました。あなたが持っていた接続をリストしたスプレッドシートを更新すること、そしてそれはそれについてでした。
それで、これを書いたので、私は完全に同意します：ステップバイステップのチェックリストは、多くのプロセスのためにそれをカットしません。
私はこれについて（徹底的なドキュメントを支持して）あなたに強く同意します。なぜなら、私はドキュメントにまったく興味がなかった前任者がいることに慣れているからです。関連する投稿で述べられているように、それを書き出すことは他の人にとって良いだけでなく、あなたの環境をより完全に理解し、あなたのown心の中でそれを固めるのに役立ちます。それ自体が終わりです。
余談ですが、多くの反発は、くだらない/存在しないドキュメント=仕事の安全性という奇妙な信念から来ていることがわかりました。そのような考え方は、不誠実で陰気なようです。
現状を打破してくれたことを称賛します。
私はかなり多くの文書を作成し、文書の優先順位チェックリストも持っています:-)しかし、一般的な知識と見なすことができるものは文書化しません（つまり、問題の合理的な適切な説明は、グーグルの最初のページ内で答えを与えます）。
ここに興味のある人は私のdocprioチェックリストです（私のために働く、あなたのためではないかもしれません、コメントと提案は大歓迎です）：
- あなたが仕事/知識を賢くしたことをすべて書き留める個人的なログ/日記を作成します
- サービス、どのサービスがどこにあり、何をし、誰のために行われるか（SLA契約？作成する必要がありますか？）
- サーバー、どのサーバーがどこにあり、何歳で、いつ書かれているのか
- 上記と同じですが、ネットワーク機器、UPSなどの場合
- 上記と同じですが、すべてのユーザーマシン用です
- 物理ネットワークのレイアウト（どのケーブルがどこに行くか、どのくらいの長さで、測定された品質はどれくらいか）
- サーバーのソフトウェアとライセンスの構成の概要
- ユーザーマシンのソフトウェアとライセンスの構成の概要
- スイッチ、ルーター、その他の専用ハードウェアの構成の概要
- 私のサービスが直接依存しているすべての外部関係者の契約とSLA（ISP、ドメインなど））
- 上記のすべてのものを入れるために、統合されたwikiを使用してチケットシステムをセットアップします。
- インシデントごとにチケットを作成します（自分だけに使用する場合でも）。
- 日曜日にチケットを収集し、問題の種類ごとにグループ化するスクリプトを作成します。
- 月曜日に、最も発生している問題の自動ソリューションまたはエンドユーザーのハウツードキュメントを作成します
- 時間が許せば、次のことをしてください。
- これ以上何もすることがない場合は、新しい仕事を探して、あなたに代わる人にログを渡してください;-)
チェックリストは、完全ドキュメントのふりをしていない限り問題ありません。私が書いた最後のいくつかのドキュメントは、2つの部分に分かれていました。XYZforUsersには、使用方法に関するきれいなスクリーンショットが含まれていました。システム管理者向けのXYZには、セットアップ方法とその理由（場合によっては、存在するためのビジネス要件も含まれます）、回避するトラップ、およびトラブルシューティングに関するセクションが含まれています。トラブルシューティングは、私がチェックリストを見つけることを期待するところです。おそらく、テクニカルサポート用のXYZとしてチェックリストを書くことは、ポイントを作るのに役立つかもしれません。
さて、チェックリストだけに焦点を当てて行間を読むと、次のような人に期待する「全体像」の考え方と長期計画が不足していることがわかります。または、始めたばかりのジュニア管理者。または、仕事に忙殺されて、それについて考える時間がありません。またはそれについて考えるように強制されたことはありません。または単にプレーンは気にしません。あなたの場合、これらのどれが当てはまるかわかりません。
私はドキュメンテーションがかなり得意です。私が働いている会社は、ドキュメントが重要だと感じていますが、会社の中にはドキュメントを書く時間がないと感じている人もいます。これは、最初にそれをした人以外の誰にとっても人生を困難にする可能性があります。
特定の事柄について、私は段階的な指示を書きました。必要に応じてこれをチェックリストと呼ぶことができますが、実際には物理的にチェックオフすることを意図したものではありません。私は自分のドキュメンテーションスタイルを「幼稚園のステップ」と呼んでいます。これは、Windows2000試験の1つで持っていたMCSE練習帳を模したものです。手順は非常に詳細ですが、太字/斜体/書体を使用すると、簡単に理解して重要な部分を選択できるため、手順を学習した後ですべてを読む必要はありません。
ステップバイステップの説明に適さないものもあるので、できるだけ多くの構成データを提供するようにしています。技術的に傾倒している人の中には、自分が何に反対しているのかをよりよく理解し、何かがうまくいかなかったときに少し楽になることを願っています。