私は、さまざまな役割を持つ多数のマシンで構成されるまったく新しいラボ環境のセットアップと管理を任されています。VM ホスト、複数の Web サーバー、複数のデータベース サーバーなどがあります。
このラボ環境の一部として文書化する必要がある非常に具体的なニーズとプロセスがあります。たとえば、自動 Windows 更新をオンにしたくない、複数の異なる関係者 (役員、マネージャー、開発者、IT マネージャー、QA 担当者) に説明するために記録したい考えがたくさんあります。
セットアップ中に、これらの会話を何らかの正式な文書に記録しておきたいと思いました。Word の .doc を作成し、各サーバー ロールをいくつかの個別のセクションに整理するつもりでした。
- エグゼクティブサマリー
- メンテナンスの必要性
- インストールされたソフトウェアのインベントリ
- 利用可能なハードウェア
- ハードウェアのデフォルト
私が知りたいのは、これらのマシンのドキュメントを作成するときに、従うことができるよりよいテンプレートがあるかどうかです。私が最終的に作成したものが、必要に応じて他の誰かがマシンを再構築するのに十分なものであることを願っています。
答え1
優れたドキュメント システムにとって最も重要なことは次のとおりです。
- 簡単に更新できる（そうでないと、更新しない人が増えて、役に立たなくなるどころか、さらに悪くなる）
- どこからでも、複数のデバイスから簡単にアクセスできます。
- 適切に整理されており、必要な情報を簡単に見つけることができ、同じ情報の重複が最小限に抑えられています。
Word 文書を試してみましたが、3 つのポイントすべてで失敗しました。Word 文書は更新が難しく、最終的には各自が異なるコピーを持つことになります。
私が見つけた、自分にとって最適なシステムは Wiki です。DokuWiki は私の目的に非常によく合っています。どこからでも簡単にアクセスして更新できます。
私の Wiki は、ネットワーク設定全体を説明するページで構成されており、各サーバー、クラスター、アプリケーションのページにリンクされています。この方法では、特定の項目に関するすべての詳細が別々のページに保存され、関連するすべての場所からリンクできます。何かが変更された場合は、1 つのページで変更するだけで、探している情報を簡単に見つけることができます。
また、名前空間テンプレートを指定することもできます。そのため、新しいサーバー ページを作成すると、IP アドレスやハードウェア構成などを入力するためのテーブルが事前に入力されます。空のフィールドにはすべて FIXME が書き込まれているため、Wiki 全体で FIXME を検索し、ドキュメントに何が欠けているかを確認できます。
本当に凝ったことをしたいなら、設定ファイルなどを取得して解析し、読みやすい形式で表示するプラグインを書くことができます。たとえば、私は PatchPanel というプラグインを書きました。これは、ネットワーク パッチ パネルのテキスト記述を取得して、各ポートが接続される場所のラベルを付けてその画像を描画します。
http://blog.emsley.ca/2014/04/documentation.html設定方法については、より詳しい説明があります (免責事項: 私のブログへのリンクですが、完全にトピックに沿った内容です)。