Как стать автором
Обновить

Еще раз о документации

Время на прочтение 6 мин
Количество просмотров 18K
Уровень: начинающим, продолжающим, ленивым

Что, опять? Но зачем!?


О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может быть мягкой и шелковистой легкой и приятной.





В чем вести документацию?


Я считаю, что есть только один нормальный способо вести документацию. Спросите себя какой? Я думаю, вы угадали что это вики. Почему? Про возможности совместной работы я даже не буду упоминать, это очевидно. Главные преимущества вики-системы я вижу в следующем:
1. Сохраняется история правок. Всегда можно посмотреть, кто виноват и кому в башку сапог.
2. Простота установки, настройки и использования. Вики можно использовать везде.

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


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

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


Я люблю красивые схемы, но использую их только в крайнем случае, потому у них есть несколько принципиальных недостатков.
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[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. Так что если вам не страшно отдавать свои данные на откуп корпорации бобра — дерзайте.
Теги:
Хабы:
+14
Комментарии 33
Комментарии Комментарии 33

Публикации

Истории

Работа

Ближайшие события

Московский туристический хакатон
Дата 23 марта – 7 апреля
Место
Москва Онлайн
Геймтон «DatsEdenSpace» от DatsTeam
Дата 5 – 6 апреля
Время 17:00 – 20:00
Место
Онлайн
PG Bootcamp 2024
Дата 16 апреля
Время 09:30 – 21:00
Место
Минск Онлайн
EvaConf 2024
Дата 16 апреля
Время 11:00 – 16:00
Место
Москва Онлайн