Меню

Кадровые документы для ИП

0 комментариев

Документация на сервера

Документацию я веду преимущественно текстовую. Но сейчас я отклонюсь от темы и расскажу про схемы.

Отсупление про графические схемы

Я люблю красивые схемы, но использую их только в крайнем случае, потому у них есть несколько принципиальных недостатков.
1. Схему нужно скачивать из вики, менять и заливать обратно. Этот недостаток насколько важен, что я остановлюсь на нем особо. Итак, ключевое условие для своевременного ведения документации состоит в принципах «документируй по ходу работы» и «документируй легко». Для изменения документации нужно совершать минимальное количество действий. И правда, если для того, чтобы задокументировать измение в топологии сети или в схеме работы кластера нужно открывать схему, изменять ее и заливать обратно, есть довольно большая вероятность что делать этого просто не будут. А даже если будут, то совсем не радостно, потому что это весьма муторно.
2. По схемам нельзя искать. И даже если искать по схемам в программе создания схем можно, то навряд ли это будет работать когда схема, вероятнее всего преобразованная в картинку, будет вставлена в вики.
3. Схема не заменит грамнотное словесное описание. Конечно, есть вещи для которых схемы подходят больше, но в своей повседневной практике я столкнулся с тем, что большинство вещей с которыми я работаю отлично описываются текстом, а схемы иногда лепят просто для красоты.

Итак, текст

Я люблю текст. Скажу даже больше, я люблю plaintext. Он быстро набирается и достаточно выразителен, если правильно использовать отступы, причем позволяет сосредоточиться на структуре а не на оформлении. Структура это самое главное. Поэтому еще раз скажу: «Используйте отступы!» Они позволяют сосредоточиться на том что вы описываете не отвелкаясь на оформление, и при этом представить информацию удобной, структурированной и легкой для восприятия форме. Может немного перехвалил? Ну да ладно.
Итак, несколько принципов работы с текстом:
1. Документацию пишут для того, чтобы ее читать. Поэтому при разработке формата документации отталкивайтесь исключительно оттого, что сможет помочь вам в работе. Спрашивайсте себя «Что я должен знать об этом сервисе? Об этой машине?»

2. Пишите лаконичо. Если что-то можно не писать, потому что оно уже где-то есть, то не пишите, потому что по опыту получаются дебри текста, на которые затем просто забивают. Наприметр, спецификации сервера можно указать ссылкой на документ на сайте производителя. Итак, нет избыточности и лишней работе!
3. Не пишите, копируйте! Если что-то можно взять прямо из конфига, берите прямо из конфига. Вывод команды тоже пойдет. Если можно сделать скрипт, которым сам выдергивает информацию из конфигов и кладет в вики (а это несложно) — делайте. Документацию на сами сервера можно класть в /etc/motd и потом выгружать в вики, тогда документировать изменения будет намного проще вообще всем.
3. Структурирование — наше все. Выделяйте отступами подчиненные элементы. Можно использовать списки, но списки это хорошо, а отступы лучше.
4. Стандарты документации должны быть, но здравый смысл важнее. Например, если в функционировании сервера есть некоторые неявные особенности, делайте новый подраздел и пишите. Если с сервером что-то не так, выносите это наверх и выделяйте красным.
5. Мониторинг это не документация. Системы управления конфигурацией тоже не документация. Понятно, что если есть 100 однотипных серверов, то можно задокументировать только один но, с другой стороны, если у вас есть 100 однотипных серверов, то вы и так это знаете.

Шаблон для описания сервера

Итак, ниже представлен шаблон для описания сервера. В настоящей вики он выглядит примерно также, как и тут. Как видите, я настолько люблю отступы, что действительно использую очень много тегов pre 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 Ротация: 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 Ротация: 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/

Напоследок

Приведенные выше примеры не обязательно применимы к вам напрямую, их можно и нужно переделывать под обстоятельства.
Ну вот и все. Всем привет!
UPDATE: Как резонно заметил в комментариях VolCh, а потом еще и powerman, удобно использовать для документации систему контроля версий и работать с документацией как с кодом. Объяснение почему есть в комментариях. Далее можно поступить как описано powermanом тут, на мой взгляд очень хорошее решение: habrahabr.ru/post/12903
UPDATE2: Добавил мысли по поводу документация в репозитарии vs документация в вики:
За вики:
— Если с документацией работают не только разработчики, то намного проще использовать вики
— В вики легче привести документацию к одному виду, не будет разброда и шатания (из опыта)
— К вики легко приделываются роботы, так что преимущества репозитория неочевидны
— Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы
За репозитарий:
— Разработчикам скорее всего проще будет использовать репозитарий, единая система для всего
— Роботы приделываются легче чем в вики
— Если уже есть документация в html-формате ее за минуту к вики не подошьешь, а в репозитарий положишь запросто
В целом, всегда нужно выбирать по обстоятельствам. Если в команде одни разработчики и есть четкие стандарты на все — репозитарий, если не только разработчики или плохо со стандартами — вики, если есть еще какие-то факторы — учитывайте их.

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *