ドキュメントの使用を開始する

私たちは職場でドキュメントを作成していません。私はまったく新しいので、始めにいくつかのガイダンスを求めます。

いくつかの質問を聞きたいんです：

• システム管理者が作成および保守する必要がある重要なドキュメントは何ですか？そして、なぜこれらはとても重要なのでしょうか？

• ドキュメントをシステムとどのように同期させますか？情報の重複をどのように最小限に抑えますか？

• 推奨ガイド、ベストプラクティス、アンチパターン？

2003年以降、社内wikiにすべてを文書化しています。

サーバー

• ハードウェア仕様
• 保証情報
• ネットワーク情報
• そしてもちろんインストールされたソフトウェアと設定

ワークフロー

たとえば、ユーザーを追加または削除し、関連するすべてのサービスへのアクセスを許可する方法

重要なリンク

• すべてのWebインターフェイスへのリンク
• 監視URLへのリンク（nagios、munin、apc-monitoring ...）
• Wikiへのリンク（印刷版の場合！）

緊急の指示

イントラネットサーバー/インターネット/ウェブサーバーなどがダウンした場合の対処方法

重要：

PDFに簡単にエクスポートできるWikiエンジンを選択してください！
休暇中、wikiを実行しているサーバーがダウンしていて、ドキュメントがオフラインであるため、誰が何をすべきかわからない場合は役に立ちません

twiki、docuwiki、mediawikiをご覧ください。

ところで：

MediaWikiに直接書き込むためのOpenOffice.orgプラグインがあります-非常に便利です。

編集：

また、いくつかの情報を書き留めておくと便利です/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）1つの真実のソースを作成せず、人々にそれを追い詰めることを強制しないでください。アイデアが重要であればあるほど、それを繰り返す必要があります。

必須ドキュメント：

• サーバーのドキュメント-仕様/ディスクレイアウト/インストールされたソフトウェア/その他の注意事項
• 一般的な手順-「自明」ではないことが行われた場合は、特に手順がまだ行われていない場合は、手順を文書化する必要があります。

ドキュメントの同期を維持することは、「間違いがあれば修正する」ことになります。これに伴い、文書が古くなったり、古くなったりする可能性があり、これを考慮せずに盲目的に従うべきではないことを認識する必要があります。ドキュメントは、重要な思考に取って代わるルールの段階的なセットではなく、タスクで管理者を支援するためにあります。

重複を最小限に抑える-Wikiのようにドキュメントをリンクできるものを使用すると、情報を繰り返すのではなく、リンクするだけで済みます。問題は、ドキュメントを書く人が、複製しようとしている情報がすでに存在することを知る必要があるということです。これは通常、良い組織の問題です。

テンプレートの作成は大きな助けになることがわかりました。私の場合、それはWordテンプレートですが、あなたに合ったものを使用します。必要に応じて目次フィールドとセクションを備えたスケルトンファイルを作成します。数回使用し、微調整を行ったら、新しいドキュメントをより迅速に作成できます。フォーマットの一貫性は、ドキュメントの作成とその後の使用の両方に非常に役立ちます。ドキュメントは、論理的な場所と論理的なディレクトリ構造に保存する必要があります。

個人的には、維持が不必要に難しく、時間がかかるという単純な事実の繰り返しに反対しています。文書または文書の一部を複製するのではなく、必要に応じて他の文書への参照を作成します。何かが、あなたはもっとして一回または複数の場所で関連文書を変更する必要はありません変更した場合はそうしないだろう誰を助けない矛盾文書のコレクションを持っています。

ドキュメントを作成するときは、その目的を念頭に置いてください。後で誰かがそれを使用する必要があります。事前の知識なしで仕事をすることは有用でしょうか？

あなたの質問への直接的な答えではなく、正しい方向への指針：

LimoncelliとHogan（別名Sysadmin Bible）によるSystem and Network Administrationの実践は、ドキュメントなどの「ベストプラクティス」の問題に関するものであるため、非常に価値があることがわかりました。まだ知らない場合は、機会があればいつでも調査してください。

私にとって最も重要な考慮事項は、使いやすくすることです。オーケストレーションが難しい場合、人々はそれを避けます。これらの理由から、ドキュメントの媒体としてTracのwiki を選択します。

• 中央に位置します。

  1つのドキュメントの複数のアクティブコピーが混乱を招きます。寄稿者と聴衆の両方を同じ場所に紹介することができれば、プロセスを簡素化できます。

• 簡単な編集とフォーマット。

  かなりの時間がWordのきれいなテンプレートに浪費され、最後の作者のスタイルに準拠しています。あなたがこれで人々を泥沼にしないなら、外出先で編集するのがより簡単で、貢献者はそうする傾向があります。TracLinksを使用して、必要なだけアイテムを分離します。

• 監査履歴。

  誰がどのような変更を、いつ、なぜ行ったかを知ることが重要です。それを変更要求チケットと構成コミットログに結び付けることができれば、さらに良いでしょう。SVNコミットフックはこれに最適です。