Уровень: начинающим, продолжающим, ленивым
О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может бытьмягкой и шелковистой легкой и приятной.
Я считаю, что есть только один нормальный способо вести документацию. Спросите себя какой? Я думаю, вы угадали что это вики. Почему? Про возможности совместной работы я даже не буду упоминать, это очевидно. Главные преимущества вики-системы я вижу в следующем:
1. Сохраняется история правок. Всегда можно посмотреть, кто виновати кому в башку сапог.
2. Простота установки, настройки и использования. Вики можно использовать везде.
Документацию я веду преимущественно текстовую. Но сейчас я отклонюсь от темы и расскажу про схемы.
Я люблю красивые схемы, но исп��льзую их только в крайнем случае, потому у них есть несколько принципиальных недостатков.
1. Схему нужно скачивать из вики, менять и заливать обратно. Этот недостаток насколько важен, что я остановлюсь на нем особо. Итак, ключевое условие для своевременного ведения документации состоит в принципах «документируй по ходу работы» и «документируй легко». Для изменения документации нужно совершать минимальное количество действий. И правда, если для того, чтобы задокументировать измение в топологии сети или в схеме работы кластера нужно открывать схему, изменять ее и заливать обратно, есть довольно большая вероятность что делать этого просто не будут. А даже если будут, то совсем не радостно, потому что это весьма муторно.
2. По схемам нельзя искать. И даже если искать по схемам в программе создания схем можно, то навряд ли это будет работать когда схема, вероятнее всего преобразованная в картинку, будет вставлена в вики.
3. Схема не заменит грамнотное словесное описание. Конечно, есть вещи для которых схемы подходят больше, но в своей повседневной практике я столкнулся с тем, что большинство вещей с которыми я работаю отлично описываются текстом, а схемы иногда лепят просто для красоты.
Я люблю текст. Скажу даже больше, я люблю plaintext. Он быстро набирается и достаточно выразителен, если правильно использовать отступы, причем позволяет сосредоточиться на структуре а не на оформлении. Структура это самое главное. Поэтому еще раз скажу: «Используйте отступы!» Они позволяют сосредоточиться на том что вы описываете не отвелкаясь на оформление, и при этом представить информацию удобной, структурированной и легкой для восприятия форме. Может немного перехвалил? Ну да ладно.
Итак, несколько принципов работы с текстом:
1. Документацию пишут для того, чтобы ее читать. Поэтому при разработке формата документации отталкивайтесь исключительно оттого, что сможет помочь вам в работе. Спрашивайсте себя «Что я должен знать об этом сервисе? Об этой машине?»
2. Пишите лаконичо. Если что-то можно не писать, потому что оно уже где-то есть, то не пишите, потому что по опыту получаются дебри текста, на которые затем просто забивают. Наприметр, спецификации сервера можно указать ссылкой на документ на сайте производителя. Итак, нет избыточности и лишней работе!
3. Не пишите, копируйте! Если что-то можно взять прямо из конфига, берите прямо из конфига. Вывод команды тоже пойдет. Если можно сделать скрипт, которым сам выдергивает информацию из конфигов и кладет в вики (а это несложно) — делайте. Документацию на сами сервера можно класть в /etc/motd и потом выгружать в вики, тогда документировать изменения будет намного проще вообще всем.
3. Структурирование — наше все. Выделяйте отступами подчиненные элементы. Можно использовать списки, но списки это хорошо, а отступы лучше.
4. Стандарты документации должны быть, но здравый смысл важнее. Например, если в функционировании сервера есть некоторые неявные особенности, делайте новый подраздел и пишите. Если с сервером что-то не так, выносите это наверх и выделяйте красным.
5. Мониторинг это не документация. Системы управления конфигурацией тоже не документация. Понятно, что если есть 100 однотипных серверов, то можно задокументировать только один но, с другой стороны, если у вас есть 100 однотипных серверов, то вы и так это знаете.
Итак, ниже представлен шаблон для описания сервера. В настоящей вики он выглядит примерно также, как и тут. Как видите, я настолько люблю отступы, что действительно использую очень много тегов pre prepre.
Cам шаблон состоит из следующих пунктов:
1. Имя сервера
2. Предоставляемые сервисы
3. Отвественные
4. Система
5. Мониторинг
6. Бэкап
Как показала практика, это самая главная страница. Она намно��о чаще используется, чем страницы отдельных серверов. Смысл этой страницы прост: в одном месте, максимально простым способом, описать возможно полную картину взаимодействия всех машин.
Формат документации простой. Для каждого сервиса (демона) на хосте записываются все хосты и сервисы с которыми описываемый сервис взаимодействует.
Приведенные выше примеры не обязательно применимы к вам напрямую, их можно и нужно переделывать под обстоятельства.
Ну вот и все. Всем привет!
UPDATE: Как резонно заметил в комментариях VolCh, а потом еще и powerman, удобно использовать для документации систему контроля версий и работать с документацией как с кодом. Объяснение почему есть в комментариях. Далее мо��но поступить как описано powermanом тут, на мой взгляд очень хорошее решение: habrahabr.ru/post/12903
UPDATE2: Добавил мысли по поводу документация в репозитарии vs документация в вики:
За вики:
— Если с документацией работают не только разработчики, то намного проще использовать вики
— В вики легче привести документацию к одному виду, не будет разброда и шатания (из опыта)
— К вики легко приделываются роботы, так что преимущества репозитория неочевидны
— Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы
За репозитарий:
— Разработчикам скорее всего проще будет использовать репозитарий, единая система для всего
— Роботы приделываются легче чем в вики
— Если уже есть документация в html-формате ее за минуту к вики не подошьешь, а в репозитарий положишь запросто
В целом, всегда нужно выбирать по обстоятельствам. Если в команде одни разработчики и есть четкие стандарты на все — репозитарий, если не только разработчики или плохо со стандартами — вики, если есть еще какие-то факторы — учитывайте их.
UPDATE3: В комментариях dyadyavasya рассказал о том, что у него есть положительный опыт использования Google Docs. Так что если вам не страшно отдавать свои данные на откуп корпорации бобра — дерзайте.
Что, опять? Но зачем!?
О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может быть
В чем вести документацию?
Я считаю, что есть только один нормальный способо вести документацию. Спросите себя какой? Я думаю, вы угадали что это вики. Почему? Про возможности совместной работы я даже не буду упоминать, это очевидно. Главные преимущества вики-системы я вижу в следующем:
1. Сохраняется история правок. Всегда можно посмотреть, кто виноват
2. Простота установки, настройки и использования. Вики можно использовать везде.
Документация на сервера
Документацию я веду преимущественно текстовую. Но сейчас я отклонюсь от темы и расскажу про схемы.
Отсупление про графические схемы
Я люблю красивые схемы, но исп��льзую их только в крайнем случае, потому у них есть несколько принципиальных недостатков.
1. Схему нужно скачивать из вики, менять и заливать обратно. Этот недостаток насколько важен, что я остановлюсь на нем особо. Итак, ключевое условие для своевременного ведения документации состоит в принципах «документируй по ходу работы» и «документируй легко». Для изменения документации нужно совершать минимальное количество действий. И правда, если для того, чтобы задокументировать измение в топологии сети или в схеме работы кластера нужно открывать схему, изменять ее и заливать обратно, есть довольно большая вероятность что делать этого просто не будут. А даже если будут, то совсем не радостно, потому что это весьма муторно.
2. По схемам нельзя искать. И даже если искать по схемам в программе создания схем можно, то навряд ли это будет работать когда схема, вероятнее всего преобразованная в картинку, будет вставлена в вики.
3. Схема не заменит грамнотное словесное описание. Конечно, есть вещи для которых схемы подходят больше, но в своей повседневной практике я столкнулся с тем, что большинство вещей с которыми я работаю отлично описываются текстом, а схемы иногда лепят просто для красоты.
Итак, текст
Я люблю текст. Скажу даже больше, я люблю plaintext. Он быстро набирается и достаточно выразителен, если правильно использовать отступы, причем позволяет сосредоточиться на структуре а не на оформлении. Структура это самое главное. Поэтому еще раз скажу: «Используйте отступы!» Они позволяют сосредоточиться на том что вы описываете не отвелкаясь на оформление, и при этом представить информацию удобной, структурированной и легкой для восприятия форме. Может немного перехвалил? Ну да ладно.
Итак, несколько принципов работы с текстом:
1. Документацию пишут для того, чтобы ее читать. Поэтому при разработке формата документации отталкивайтесь исключительно оттого, что сможет помочь вам в работе. Спрашивайсте себя «Что я должен знать об этом сервисе? Об этой машине?»
2. Пишите лаконичо. Если что-то можно не писать, потому что оно уже где-то есть, то не пишите, потому что по опыту получаются дебри текста, на которые затем просто забивают. Наприметр, спецификации сервера можно указать ссылкой на документ на сайте производителя. Итак, нет избыточности и лишней работе!
3. Не пишите, копируйте! Если что-то можно взять прямо из конфига, берите прямо из конфига. Вывод команды тоже пойдет. Если можно сделать скрипт, которым сам выдергивает информацию из конфигов и кладет в вики (а это несложно) — делайте. Документацию на сами сервера можно класть в /etc/motd и потом выгружать в вики, тогда документировать изменения будет намного проще вообще всем.
3. Структурирование — наше все. Выделяйте отступами подчиненные элементы. Можно использовать списки, но списки это хорошо, а отступы лучше.
4. Стандарты документации должны быть, но здравый смысл важнее. Например, если в функционировании сервера есть некоторые неявные особенности, делайте новый подраздел и пишите. Если с сервером что-то не так, выносите это наверх и выделяйте красным.
5. Мониторинг это не документация. Системы управления конфигурацией тоже не документация. Понятно, что если есть 100 однотипных серверов, то можно задокументировать только один но, с другой стороны, если у вас есть 100 однотипных серверов, то вы и так это знаете.
Шаблон для описания сервера
Итак, ниже представлен шаблон для описания сервера. В настоящей вики он выглядит примерно также, как и тут. Как видите, я настолько люблю отступы, что действительно использую очень много тегов pre pre
Cам шаблон состоит из следующих пунктов:
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/
Взаимодействие между серверами
Как показала практика, это самая главная страница. Она намно��о чаще используется, чем страницы отдельных серверов. Смысл этой страницы прост: в одном месте, максимально простым способом, описать возможно полную картину взаимодействия всех машин.
Итак, если вам лень вести документацию, сделайте хотя-бы это!
Формат документации простой. Для каждого сервиса (демона) на хосте записываются все хосты и сервисы с которыми описываемый сервис взаимодействует.
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
Напоследок
Приведенные выше примеры не обязательно применимы к вам напрямую, их можно и нужно переделывать под обстоятельства.
Ну вот и все. Всем привет!
UPDATE: Как резонно заметил в комментариях VolCh, а потом еще и powerman, удобно использовать для документации систему контроля версий и работать с документацией как с кодом. Объяснение почему есть в комментариях. Далее мо��но поступить как описано powermanом тут, на мой взгляд очень хорошее решение: habrahabr.ru/post/12903
UPDATE2: Добавил мысли по поводу документация в репозитарии vs документация в вики:
За вики:
— Если с документацией работают не только разработчики, то намного проще использовать вики
— В вики легче привести документацию к одному виду, не будет разброда и шатания (из опыта)
— К вики легко приделываются роботы, так что преимущества репозитория неочевидны
— Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы
За репозитарий:
— Разработчикам скорее всего проще будет использовать репозитарий, единая система для всего
— Роботы приделываются легче чем в вики
— Если уже есть документация в html-формате ее за минуту к вики не подошьешь, а в репозитарий положишь запросто
В целом, всегда нужно выбирать по обстоятельствам. Если в команде одни разработчики и есть четкие стандарты на все — репозитарий, если не только разработчики или плохо со стандартами — вики, если есть еще какие-то факторы — учитывайте их.
UPDATE3: В комментариях dyadyavasya рассказал о том, что у него есть положительный опыт использования Google Docs. Так что если вам не страшно отдавать свои данные на откуп корпорации бобра — дерзайте.
