ドキュメントの開始
私の職場では文書化を行っていません。私はそれに完全に不慣れであり、始めるためにいくつかのガイダンスを求めます。
いくつかの質問を聞きたいんです：
システム管理者が作成および維持する必要のある重要なドキュメントは何ですか？そして、なぜこれらはそれほど重要なのでしょうか？
ドキュメントをシステムとどのように同期させますか？情報の重複を最小限に抑えるにはどうすればよいですか？
推奨ガイド、ベストプラクティス、アンチパターン？
2003年以来、私は社内のwikiですべてを文書化しています。
サーバー
- ハードウェア仕様
- 保証情報
- ネットワーク情報
- そしてもちろん、インストールされたソフトウェアと構成
ワークフロー
例えばユーザーを追加または削除して、関連するすべてのサービスへのアクセスを許可する方法
重要なリンク
- すべてのWebインターフェイスへのリンク
- モニタリングURLへのリンク（nagios、munin、apc-monitoring ...）
- ウィキへのリンク（印刷版の場合！）
緊急時の指示
イントラネットサーバー/インターネット/ウェブサーバーなどがダウンした場合の対処方法
重要：
PDFに簡単にエクスポートできるウィキエンジンを選択してください！
休暇中、Wikiを実行しているサーバーがダウンしていて、ドキュメントがオフラインであるために何をすべきかわからない場合は役に立ちません。
Twiki、docuwikiまたはmediawikiを見てください。
ところで：
OpenOffice.orgプラグイン mediawikiに直接書き込むことができます-非常に便利です。
編集：
/home/adminuser/maintenanceにいくつかの情報を書き留めておくこともできます。これは迅速に実行され、複数の管理者がサーバーで作業している場合に非常に役立ちます。例えば：
2009-06-27 -thorsten-
running aptitude update && aptitude full-upgrade
everything seems ok
2009-06-25 -andreas-
cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
deleted old log under /var/log/squid
etc.
誰もがドキュメントを望んでいる（そして必要としている）一方で、誰もがそれらを読んで研究する時間がないことを認識する必要があります。
したがって、調査が必要なドキュメントを作成しないでください。代わりに、誰かが必要なときに必要な情報をすばやく見つけられるようにドキュメントを構成してください。これは、システムがダウンしていてCTOが彼/彼女の首を呼吸します。
これを念頭に置いて、いくつかの提案...
- テキストの大きなブロックを避ける
- 箇条書きはあなたの友達です
- 明確な図は金色です
- 繰り返しは良い考えです（1）
- 更新と拡張を簡単にします
（1）one真実の情報源を作成せず、人々にそれを追い詰めるように強制します。アイデアが重要であるほど、それを繰り返す必要があります。
重要なドキュメント：
- サーバーのドキュメント-仕様/ディスクレイアウト/インストールされているソフトウェア/注意事項
- 一般的な手順-「些細な」ことではない実行されるものはすべて、特にそれが以前に実行されたことがないものである場合は、手順を文書化する必要があります。
ドキュメントの同期を維持することは、「間違いを見つけたら修正する」ことです。これに伴い、ドキュメントは古くなる可能性があり、古くなる可能性があり、これを考慮せずに盲目的に従わないようにする必要があることを認識する必要があります。ドキュメントは、管理者のタスクを支援するためのものであり、批判的思考に取って代わる一連のルールではありません。
重複を最小限に抑える-ドキュメントをリンクできるウィキのようなものを使用すると、情報を繰り返す代わりに、リンクするだけでこれを支援できます。問題は、ドキュメントを作成する人が、複製しようとしている情報がすでに存在することを知る必要があることです。これは通常、優れた組織の問題です。
テンプレートを作成することは大きな助けになることがわかりました。私の場合、これはWordテンプレートですが、自分に合ったものを使用してください。必要に応じて、目次フィールドとセクションを備えたスケルトンファイルを作成します。これを数回使用し、微調整を行うと、新しいドキュメントをはるかに高速に作成できます。フォーマットの一貫性は、ドキュメントの作成と後での使用の両方に非常に役立ちます。ドキュメントは、論理的な場所と論理的なディレクトリ構造に保存する必要があります。
維持管理が不必要に難しく、時間がかかるという単純な事実のために、私は個人的に繰り返しに反対しています。ドキュメントまたはドキュメントの一部を複製するのではなく、必要に応じて他のドキュメントへの参照を作成します。何かが変更された場合、関連するドキュメントを2回以上、または複数の場所で変更する必要はありません。変更しないと、競合するドキュメントのコレクションが作成されます。これは誰にも役立ちません。
ドキュメントを作成するときは、その目的を念頭に置いてください。後で誰かがそれを使用する必要があります。事前の知識がなくても仕事ができるのでしょうか？
あなたの質問に対する直接の答えではなく、正しい方向への指針：
LimoncelliとHogan（別名Sysadmin Bible）による システムおよびネットワーク管理の実践 は、ドキュメントなどの「ベストプラクティス」の問題に関するものであるため、非常に価値があることがわかりました。まだ知らない場合は、機会があれば必ず調べてください。
私にとって最も重要な考慮事項は、使いやすくすることです。オーケストレーションが難しい場合、人々はそれを避けます。これらの理由から、ドキュメントの媒体として Trac のwikiを選択します。
中央に位置します。
1つのドキュメントの複数のアクティブなコピーは混乱を招きます。寄稿者と聴衆の両方を含め、全員を同じ場所に紹介できる場合は、プロセスを簡素化できます。
簡単な編集とフォーマット。
きれいなWordテンプレートと、最後の作成者のスタイルに準拠するために多くの時間が無駄になっています。これで人々を困惑させなければ、外出先で編集する方が簡単で、寄稿者はそうする傾向があります。 TracLinksで必要なだけアイテムを分離します。
監査履歴。
誰が、いつ、なぜ、どのような変更を加えたかを知ることが重要です。それを変更要求チケットと構成コミットログに結び付けることができれば、さらに良いでしょう。 SVNコミットフックはこれに最適です。