Уровень: начинающим, продолжающим, ленивым
О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может бытьмягкой и шелковистой легкой и приятной.
Я считаю, что есть только один нормальный способо вести документацию. Спросите себя какой? Я думаю, вы угадали что это вики. Почему? Про возможности совместной работы я даже не буду упоминать, это очевидно. Главные преимущества вики-системы я вижу в следующем:
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. Так что если вам не страшно отдавать свои данные на откуп корпорации бобра — дерзайте.