また？ しかし、なぜ！？
ドキュメンテーションについては多くのことが言われており、Habréについてもいくつかの記事を見つけました。 しかし、私が見た記事（1、2、3、4）は、なぜ、何を文書化する必要があるのかという質問に答えます。 方法を示す2つの簡単な例と、ドキュメントが
ドキュメントとは何ですか？
ドキュメントを保管する通常の方法は1つしかないと思います。 何を自問しますか？ wikiを推測したと思います。 なんで？ コラボレーションの可能性については言及しませんが、それは明らかです。 Wikiシステムの主な利点は次のとおりです。
1.編集の履歴が保存されます。 あなたは誰が責任が
2.インストール、構成、使用が簡単。 ウィキはどこでも使用できます。
サーバーのドキュメント
私が実施する文書は主にテキストです。 しかし、今私はトピックから逸脱し、スキームについて話します。
グラフィックスキームに関する愚かさ
美しいスキームは大好きですが、いくつかの根本的な欠点があるため、最後の手段としてのみ使用しています。
1.スキームをwikiからダウンロードし、変更して記入する必要があります。 この欠点は非常に重要であるため、特に説明します。 したがって、タイムリーなドキュメントの重要な条件は、「作業中のドキュメント」と「簡単にドキュメントを作成する」という原則です。 ドキュメントを変更するには、最小限のアクションを実行する必要があります。 実際、ネットワークトポロジまたはクラスター操作スキームの変更を文書化するために、スキームを開いて変更し、それを埋め直す必要がある場合、彼らは単にこれを行わない可能性がかなり高くなります。 そして、たとえ彼らがそうであっても、それはとてもうれしくない。それはとても退屈だからだ。
2.スキームは検索できません。 また、スキームを作成するためにプログラム内のスキームで検索できる場合でも、スキームが画像に変換される可能性が高いため、Wikiに挿入されたときに機能することはほとんどありません。
3.このスキームは、文法的な言葉による説明に代わるものではありません。 もちろん、スキームがより適しているものもありますが、私の日常の練習では、私が扱うもののほとんどがテキストで完全に記述されているという事実に遭遇し、スキームは時々単に美しさのために彫刻されています。
だからテキスト
テキストが大好きです。 私はさらに言います、私は平文が大好きです。 インデントを正しく使用すると、すばやく入力され、非常に表現力が増し、デザインではなく構造に集中できます。 構造が最も重要です。 したがって、もう一度言います。「インデントを使用してください！」を使用すると、デザインに気を取られることなく、説明することに集中でき、同時に情報を便利で構造化された読みやすい形式で提示できます。 たぶん少し賞賛されていますか？ まあ。
したがって、テキストを操作するためのいくつかの原則：
1.ドキュメントは、それを読むために書かれています。 したがって、ドキュメント形式を開発するときは、それがあなたの仕事に役立つという理由だけで始めてください。 「このサービスについて何を知っておくべきですか？ この車について？」
2.簡潔に書きます。 すでにどこかにあるために何かを書けない場合は、書かないでください。経験からテキストのワイルドを取得します。 たとえば、サーバーの仕様は、製造元のWebサイトのドキュメントで参照できます。 したがって、冗長性や不要な作業はありません！
3.コピーしないでください。 構成から何かを直接取得できる場合は、構成から直接取得します。 コマンドの出力も行きます。 スクリプトを作成して、彼が構成から情報を引き出してウィキに載せる（これは簡単です）ことができれば、それを実行してください。 サーバー自体のドキュメントを/ etc / motdに入れてからwikiにアップロードすると、変更をドキュメント化することが誰にとってもはるかに簡単になります。
3.構造化は私たちのすべてです。 部下をインデントします。 リストを使用できますが、リストは適切であり、インデントはより適切です。
4.ドキュメントの標準はそうあるべきですが、常識がより重要です。 たとえば、サーバーの機能に暗黙的な機能がある場合、新しいサブセクションを作成して記述します。 サーバーに問題がある場合は、それを取り上げて赤で強調表示します。
5.監視はドキュメントではありません。 構成管理システムもドキュメントではありません。 同じタイプのサーバーが100台ある場合、ドキュメント化できるのは1台だけですが、反対に、同じタイプのサーバーが100台ある場合は、すでにそれを知っています。
サーバー記述テンプレート
そのため、以下はサーバーを説明するためのテンプレートです。 実際のウィキでは、こことほぼ同じに見えます。 ご覧のとおり、私はインデントが大好きなので、多くのpre pre
テンプレート自体は、次のアイテムで構成されています。
1.サーバー名
2.提供されるサービス
3.責任者
4.システム
5.モニタリング
6.バックアップ
サーバー名
powerconsumer.site
提供サービス
--------------------------- : , 10^100 . , memeater. : Memory eating service, socket http://bofh.ntk.net/BOFH/ 80/tcp : /usr/local/bin/cpueater init-: /etc/init.d/cpueater : /srv/bofh/cpueater : /var/log/cpueater[1,7] : every day, keeping last 7 days : http://zabbix.site/cpueater/ : /etc/cpueater/cpueater.conf ----------------------- : , . : Memory eating service, socket http://bofh.ntk.net/BOFH/ 80/tcp : /usr/local/bin/memeater init-: /etc/init.d/memeater : /srv/bofh/memeater : /var/log/memeater[1,7] : every day, keeping last 7 days : http://zabbix.site/memeater/ : /etc/memeater/memeater.conf
責任者
BOFH
システム
Debian Squeeze 6.04 Disk subsystem -------------- RAID-6 on LSI-based controller with 10 active disks and 2 hot-spares. 10.0GB ext4 / boot 10.0GB linux-swap(v1) swap 10.0GB ext4 /tmp 10.0GB ext4 /usr 20.0GB ext4 /var 40.0GB ext4 /home 20.0GB /opt 2300GB /srv/bofh Network subsystem ----------------- iface eth0 inet static address 192.168.1.10 netmask 255.255.255.0 network 129.168.1.0 gateway 192.168.1.1 up sleep 5; /sbin/ethtool -s eth0 autoneg off speed 100 duplex full
モニタリング
Zabbix-agent with custom scripts: /opt/zabbix/cpueater.py /opt/zabbix/memeater.py
バックアップ
/srv/bofh/cpueater/ /srv/bofh/memeater/
サーバーの相互運用性
実践が示しているように、これは最も重要なページです。 個々のサーバーのページよりもはるかに頻繁に使用されます。 このページの意味は簡単です。1つの場所で、可能な限り最も簡単な方法で、すべてのマシンの相互作用の完全な画像を記述することができます。
したがって、ドキュメントを保持するのが面倒な場合は、少なくともそれを行ってください！
ドキュメントの形式は単純です。 ホスト上の各サービス（デーモン）について、記述されたサービスが相互作用するすべてのホストとサービスが記録されます。
balancer.site ------------- ngnix: --> webserver0.site/ngnix: 80/tcp ngnix: --> webserver1.site/ngnix: 80/tcp webserver0.site --------------- php-fpm: --> sql.site/postgresql: 5423/tcp webserver1.site --------------- php-fpm: --> sql.site/postgresql: 5423/tcp sql.site -------- postgresql: --> backup.sql.site/postgresql: 22/tcp backup.sql.site --------------- amanda.site ----------- amanda-server: --> balancer.site/amanda-client: 30000-30100/tcp, 10800/udp amanda-server: --> webserver0.site/amanda-client: 30000-30100/tcp, 10800/udp amanda-server: --> sql.site/amanda-client: 30000-30100/tcp, 10800/udp zabbix.site ----------- zabbix-server: --> balancer.site/zabbix-agent: 10050/tcp zabbix-server: --> webserver0.site/zabbix-agent: 10050/tcp zabbix-server: --> webserver1.site/zabbix-agent: 10050/tcp zabbix-server: --> sql.site/zabbix-agent: 10050/tcp zabbix-server: --> backup.sql.site/zabbix-agent: 10050/tcp zabbix-server: --> amanda.site/zabbix-agent: 10050/tcp
最後に
上記の例は必ずしもあなたに直接適用できるわけではなく、状況に応じて変更することができます。
まあ、それだけです。 みなさんこんにちは！
更新： VolCh 、およびpowermanもコメントに合理的に記載されているように、バージョン管理システムを使用してドキュメントを作成し、コードと同様にドキュメントを操作すると便利です。 コメントにある理由の説明。 その後、ここでパワーマンが説明したように、私の意見では非常に良い解決策を行うことができます： habrahabr.ru/post/12903
更新2：リポジトリ内のドキュメントとWiki上のドキュメントについての考えを追加しました。
wikiの場合：
-開発者だけでなくドキュメントを操作する場合、Wikiを使用する方がはるかに簡単です
-ウィキでは、ドキュメントを1つのフォームにまとめるのが簡単です。混乱や動揺はありません（経験から）
-ロボットはウィキに簡単に取り付けられるため、リポジトリの利点は明らかではありません
-Wikiが大きい場合、グローバル検索を行う方が便利です。なぜなら、 インデックスがあります
リポジトリーの場合：
-開発者は、ほとんどすべてのための単一のシステムであるリポジトリを使用する方が簡単だと思うでしょう
-ロボットはウィキよりも簡単に取り付けられます
-既にhtml形式のドキュメントがある場合は、すぐにwikiにアクセスすることはなく、リポジトリに簡単に配置できます
一般に、状況に応じて常に選択する必要があります。 チームに開発者のみがいて、すべての明確な標準がある場合-開発者や悪い標準だけでなくリポジトリ-wiki、他の要因がある場合は、それらを考慮してください。
更新3：dyadyavasyaはコメントで、Google Docsを使用して前向きな経験があると述べました。 だから、もしあなたがあなたのデータをビーバー社に渡すことを恐れていないなら、それを手に入れてください。