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

    Уровень: начинающим, продолжающим, ленивым

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


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





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


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

    Similar posts

    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 33

      +1
      Схему нужно скачивать из вики, менять и заливать обратно.

      Так есть же плагины, на лету генерирующие схему из текста. Например, graphviz. А тут можно поискать и альтернативы ему.
        –1
        А вы «это» пробовали? Я пробовал, на сколько-нибудь больших схемах голову сломаешь.
          0
          Мы «это» пробовали. Вместо одной большой схемы делаете несколько маленьких. Причём можно внутри схемы сделать блоки описывающие разные сервера/сервисы кликабельными и ведущими на доку по этим серверам/сервисам.

          И вообще, насчёт «голову сломаешь» — это не вопрос использования graphviz, это вопрос того насколько лично Вы в состоянии ясно и в нужном разрезе описать схему(ы) взаимодействия ваших объектов. Потренировавшись можно подобрать такой подход к описанию этих схем, что он не только будет удобен как схема-картинка, но и вполне прост и понятен в текстовом виде (т.е. его легко править) плюс пригоден к grep-анию и прочему автоматизированному анализу.
            0
            Если есть возможность, приведите пожалуйста пример нескольких таких схем, обезличенных конечно же. Я бы хотел убедиться в своей неправоте по поводу тектовых схем и понять, как их можно использовать в действительности.
              +2
              Вот пример достаточно сложной схемы описывающей наш сервис авторизации и аутентификации, который по RPC используется другими проектами: png, source. И, надо отметить, исходник в каком-то смысле читается даже легче, чем схема. :) Для лучшего понимания схемы вот ещё легенда к ней: png, source. У легенды исходник читается сложнее, т.к. он слишком абстрактный и там слишком много разных типов объектов и связей.
          0
          Схема нам чаще нужна как инфографика — в одном представлении увидеть наложения разных данных — это совокупность многих документов.
          Мало смысла генерить схему по одному небольшому документу — его и так можно охватить взглядом.

          0
          Ну так и пишите, что у вас схемы на 100500 элементов. Что вы пробовали плагин такой-то, и столкнулись с тем-то и тем-то, а требования такие-то. Иначе вас можно неправильно понять — что в вики в принципе невозможно вести схемы.
            0
            Ответил ниже.
            –2
            Зачем 100500, уже на десятках становится сложно.

            Вот есть например замечательная программа yed. По удобству это лучший редактор графов и построитель схем который я знаю, мне лично им намного удобнее пользоваться чем даже Microsoft Visio. Он отлично продуман, очень удобен и для больших и сложных схем рулит и педалит. Кстати, он написан на java и его можно при известной сноровке встроить в вики в виде апплета. Вот это было бы нормальное, полноценное решение.

            Предложенный же вами плагин весьма неудобен в использовании, и схемы тех размеров, которые можно его с помощью создать, отлично заменяются текстом.
              0
              >Если что-то можно не писать, потому что оно уже где-то есть, то не пишите
              Меня всегда убивала документация, где для понимания смысла абзаца надо сходить по 10 ссылками из него (а там еще по 10 ссылкам). Не уж, надо хотябы кратко, но дублировать информацию.
                0
                В случае большого количества ссылок я согласен.

                Но например в случае наличия базы оборудования, которая ведется отделом закупок и в которой есть все параметры сервера, дублировать информацию еще и вики излишне, достаточно поставить ссылку.
                +1
                BOFH!

                А по теме — да, вполне себе хороший вариант. Более того, у него есть ещё одно преимущество, если в начале поставить дату редактирования и ссылку на страницу в вики, то вполне можно это хозяйство сохранить на самом сервере в обычном txt. Что позволит иметь крупицу данных для анализа и (при необходимости восстановления) даже если вики канет в лету по любой причине.

                Чёрт, оказывается в статье это уже есть (/etc/motd). Тогда, тогда…

                О! Знаю! ТАКИЕ конфиги — можно просто распечатать (даже на Epson LQ-100, хехе) и убрать на удалённую площадку. Осталось понять зачем =)
                  0
                  Можно стенку обклеить. Почему нет? :)
                  +1
                  У схем и прочих векторных по сути рисунков есть ещё один важный недостаток — редактировать bmp/png/gif сложно, а другое браузеры не отображают. То есть нам нужно хранить и оригинал в формате (графического?) редактора, и экспорт оригинала в растр, понимаемый браузерами. И не только хранить, но и не забывать синхронизировать. Есть, конечно, SVG, но не всегда он применим.

                  А вообще не вики единой. Те же возможности (групповая работа, история правок, использование везде(?) ) и даже больше (ветви, слияние, тэги, хуки и т. п.) дают VCS. И, имхо, позволяют более удобно автоматизировать поддержку актуальности документации. Что-то вроде: по коммиту или пушу в /etc вызывается sed, который заменяет старый конфиг (или его фрагмент) в документации, которая тоже под управлением VCS и коммитится после замены, о чём ответственным отправляется уведомление по мылу. Вероятно подобный сценарий можно реализовать и с помощью вики, но мне кажется сложнее чем пятком строк скрипта.
                    0
                    Вариант с документаций в svn/git мне очень нравится. Это наверное даже лучше чем в вики, я не вижу явных недостатков.
                      0
                      Вариант с документаций в svn/git мне очень нравится. Это наверное даже лучше чем в вики, я не вижу явных недостатков.
                        0
                        Ой блин, телефон очень жестоко
                          0
                          Ко мне отнесся. Дико не хватает возможности удалить комментарии, хотя-бы в первые 5 минут после написания.
                        +2
                        Что касается использования вики, то у этого подхода есть один довольно важный недостаток: в качестве текстового редактора вики используют textarea в браузере, и этот редактор катастрофически менее удобен, надёжен, привычен и функционален чем основной текстовый редактор используемый админами/разработчиками (вроде Vim/Emacs). Textarea в браузере годится для комментирования, максимум для редкого написания небольших статей. А документации обычно приходится писать довольно много, причём не редко нужно проводить над ней массовые операции поиска/замены — всё это делать на веб-страничках с вики крайне неудобно. И практика показывает, что удобство написания документации это один из ключевых факторов — доку и так никто писать не любит, а если её писать ещё и не удобно, то её вообще избегают писать.

                        Поэтому на мой взгляд документацию гораздо удобнее писать в обычных текстовых файлах. Версионирование обеспечивать любой системой контроля версий. А веб-сайт документации может работать в режиме read-only просто показывая документацию с красивыми стилями и автоматически сгенерированными схемами.

                        Более детально я описал наш подход в статье Использование asciidoc для документирования проекта.
                          0
                          Хороший подход, добавил его в конец статьи. Единственное замечание:
                          Что касается использования вики, то у этого подхода есть один довольно важный недостаток: в качестве текстового редактора вики используют textarea в браузере, и этот редактор катастрофически менее удобен, надёжен, привычен и функционален чем основной текстовый редактор используемый админами/разработчиками (вроде Vim/Emacs).

                          Вместо textarea всегда можно использовать костыль наподобие такого: addons.mozilla.org/en-US/firefox/addon/its-all-text/ Таким образом я довольно большую часть текстов набираю в vim.

                          Что же касается глобальных поиска и замены, то набор файликов и VCS удобнее всего.
                            0
                            Поговорил с ребятами, в пользу вики есть еще несколько аргументов:
                            — Если с документацией работают не только разработчики, то намного проще использовать вики
                            — В вики легче привести документацию к одному виду, не будет разброда и шатания (из опыта)
                            — К вики легко приделываются роботы, так что преимущества репозитория неочевидны
                            — Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы

                            Есть и недостатки, например если уже есть документация в html-формате ее за минуту к вики не подошьешь.

                            В целом, всегда нужно выбирать по обстоятельствам. Если в команде одни разработчики и есть четкие стандарты на все — репозитарий, если не только разработчики или плохо со стандартами — вики.
                              0
                              Если с документацией работают не только разработчики, то намного проще использовать вики
                              На самом деле технически эти два подхода совершенно не конфликтуют, а отлично дополняют друг-друга. Текстовые файлы в репозитории всё-равно пишутся используя вики-подобную разметку (asciidoc, markdown, etc.) и доступны для просмотра через сайт (что даёт красивое/наглядное форматирование текста, встроенные схемы/картинки, и работающие гиперссылки), и никто не мешает реализовать их редактирование через сайт как обычную вики (с commit-ом в репозиторий каждого изменения странички через веб-интерфейс). Такую документацию можно читать/писать и в обычных файлах и через сайт, и каждый может использовать тот способ, который лично ему удобнее.
                              В вики легче привести документацию к одному виду, не будет разброда и шатания
                              Разброд и шатание в данном случае (когда хоть в текстовом файле хоть в вики можно писать что и как угодно, нет жёсткой формы для ввода данных) никак не зависят от используемого технического решения.
                              К вики легко приделываются роботы
                              Да ладно. Роботов гораздо проще приделать к каталогу с текстовыми файлами, чем к веб-сайту.
                              Если вики большая, по ней удобнее делать глобальный поиск, т.к. есть индексы
                              Я не слышал о проектах, по которым столько документации, что grep по ней настолько тормозит что для ускорения поиска нужны индексы. Но, в любом случае, как я уже говорил выше, индексация как часть фич вики-интерфейса никак не конфликтует с работой с докой как с файлами.
                              В целом, всегда нужно выбирать по обстоятельствам.
                              Разумеется.
                                0
                                > На самом деле технически эти два подхода совершенно не конфликтуют, а отлично дополняют друг-друга. (...)

                                А как реализовано редактирование страниц из браузера?

                                > Разброд и шатание в данном случае (когда хоть в текстовом файле хоть в вики можно писать что и как угодно, нет жёсткой формы для ввода данных) никак не зависят от используемого технического решения.

                                Как показывает практика, зависят. Непрограммистам с вики жить легче. Хотя, возможно это у меня такая выборка.

                                > Да ладно. Роботов гораздо проще приделать к каталогу с текстовыми файлами, чем к веб-сайту.

                                Я об этом написал в UPDATE к статье.
                            0
                            А лучше пойти еще дальше. Использовать chef (puppet etc) и ваша конфигурация становится вашей документацией, а еще бекапом. В дополнение к этому получаем тестирование, контроль версий и многое другое. DevOpts решает.
                              0
                              Конфигурация =/= документация. Вы же не будете говорить, что сам исходный код является докуменацией на себя?

                              Я систему управления конфигурацией упомянул в статье.
                                0
                                Вот как раз об этом я и говорю. Он становится документацией и это очень здорово работает. Мы постоянно включаем новых людей в инфраструктуру проектов (десятки проектов, десятки серверов), причем все чаще самих разработчиков, т.к. по сути управление конфигурацией становится программированием.
                                  0
                                  Но, естественно, документация не исключается, просто ее необходимость (и объем) возникает несравненно реже.
                                    0
                                    Получается, что документировать конфигурацию нужно также, как код. Плюс, многие общие вещи из конфигов не ясны, нужно делать отдельное описание архитектуры. Это особенно актуально для «десятки проектов, десятки серверов», потому что иначе взаимодействие всего со всем превращается в дикую кашу, которую никто не понимает. Сталкивался :)
                              0
                              Мы используем для работы с документацейи Google Docs:

                              1) Удобный редактор
                              2) Доступ отовсюду
                              3) Расшаривание (ридонли и с возможностью редактирования)
                              4) Командная работа
                              5) Хранение версий
                              6) Комментирование участков текста
                              7) Встроенные схемы (со всеми вышеперечисленными плюшками)
                              8) Экспорт в doc, pdf или публикация в виде html

                              Вроде всё что нужно.
                              P.S. Да и недавно запущенный google drive добавляет плюсов в виде прикрепления файлов и синхронизацией с десктопом.
                                0
                                Ответил ниже.
                                0
                                Для среднекрупных компаний это решение неприемлемо просто в силу факта хранения данных на серверах google.

                                Кроме того, как я уже писал документация частично пишется роботами. Насколько просто прицепить роботов к googledocs?
                                  0
                                  Вообще-то я знаю средние компании, которые используют гугловую почту для своего домена, так что для них, использование google docs в норме.
                                  Так как google docs сейчас интегрирован в google drive, то работать роботу с ним просто — только складывай новые файлы в папку на диске или меняй их.
                                    0
                                    В принципе тоже вариант. Добавил в статью, кому-нибудь пригодится.

                                Only users with full accounts can post comments. Log in, please.