Документация нужна. Точка. На этом всё, расходимся.

На самом деле, если без шуток, что такое техническая документация? Зачем она нужна? Вопросы интересные. Если отвечать на них бюрократическим языком, то получится длинно, важно и непонятно. Поэтому мы попробуем ответить по-простому.

Документация — это про знания. Знания о продукте, системе, процессах. Важно, где и как хранятся эти знания, кто может получить к ним доступ, легко ли их найти, доступны ли они для понимания.

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

И наконец, документация — это про коммуникацию. Про передачу информации между людьми, отделами, компаниями и т.д. Например, документация API позволяет заменить коммуникацию между группами разработчиков, пользовательская документация — это способ коммуникации между компанией-разработчиком и ее клиентами, инструкции для новых сотрудников — это замена общения наставника и новичка.

Итак, если документация позволяет управлять знаниями, заменяя другие виды коммуникации и принося при этом деньги или решая задачу бизнеса, то такая документация нужна и важна.

Отвечает ли этим параметрам техническая документация?

Ну, как всегда, зависит от того, что внутри. Но прежде надо определиться с тем, что снаружи — с определением технической документации. Его можно сформулировать так:

Техническая документация — это некоторое количество документов, в которых содержится информация об устройстве продукта или системы, как ими пользоваться, какие могут быть проблемы и как их решать, схемах работы, взаимодействии разных частей и многое другое.

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

В чём польза, брат?

В нашей компании для каждого нового заказчика, пришедшего к нам на поддержку, мы создаём документацию по инфраструктуре его проекта. В ней описывается, из чего состоит проект, какие есть сервисы, как они взаимодействуют, как и какая информация передаётся, какие есть контуры в проекте, каковы настройки автоматизации и процессы CI/CD. Ещё добавляем инструкции по решению возникающих проблем, инструкции от клиента, регламенты реагирования на алерты и многое другое.

Поверьте, это довольно обширная работа, в которой задействован далеко не один человек. Зачем так осложнять себе жизнь? — Затем, что мы не осложняем, а упрощаем её. Наличие подробной документации позволяет сэкономить время при работе с клиентской инфраструктурой. Например, чтобы быстро понять, что и где расположено, есть ли репликации у баз данных, настроен ли мониторинг и где хранятся логи.

Документация помогает как текущим сотрудникам при проведении плановых и экстренных работ, так и новым сотрудникам в процессе онбординга. Новый сотрудник тем быстрее приступит к своим обязанностям, чем быстрее вникнет в работу, в том числе разберется, как построена и из чего состоит инфраструктура проекта.

Также наличие документации помогает при внедрении глобальных инфраструктурных изменений, например, при переезде с одного технологического стека на другой. Важно задокументировать существующий порядок, составить схему для будущей инфраструктуры и, конечно же, описывать изменения, которые происходят в проекте. И тогда в процессе переноса инженеры смогут в любой момент максимально быстро получить необходимую информацию.

Но документация нужна и архиполезна не только для нас, но и для самих наших заказчиков. Например, она помогает не только иметь чёткое представление, из чего состоит их система, но и заметить возможные лишние компоненты. Согласитесь, довольно обидно платить деньги за те ресурсы, которые потеряли свою актуальность и не используются. А в документации такое сразу увидишь.

Документы с особенностями

Штука в том, что у каждого проекта своя уникальная инфраструктура. К примеру, у первого есть только один сервер, на котором крутится и база, и веб-сервер, и, допустим, почтовый клиент. А у второго — десятки серверов, каждый из которых отвечают за свою роль. В третьем всё крутится на железных серверах и виртуалках, а в четвёртом часть проекта или он весь расположены в облаке. А ещё где-то там настроен кластер Kubernetes, который конфигурируется при помощи Ansible…

Такое разнообразие инфраструктур представляет определенную сложность для составления документации. Например, какая информация нужна нашим админам, а что будет лишним? К какому виду привести информацию, чтобы она была удобна для восприятия? Какая нужна структура документации, чтобы можно было легко ориентироваться во всех проектах, что у нас на поддержке? А какая информация должна быть в документации, чтобы та была полезна не только нам, но и заказчикам?

Впридачу если ПО меняется чаще всего по релизам и более-менее предсказуемо, то в современном DevOps-мире инфраструктура — вещь довольно изменчивая, и очень важно выделить те моменты, которые необходимо обязательно задокументировать.

На все вышеприведённые вопросы беглый и обстоятельный гуглинг не дали ответа: релевантных примеров, которую можно было бы взять за основу, в открытом доступе мы не нашли. Поэтому практически всё пришлось разрабатывать с нуля. Так появилась общая структура для всех проектов, были выделены основные компоненты и сервисы, наличие которых “в обяз” нужно указывать в документации, определены важные пункты в их конфигурациях, которые тоже необходимо внести в документацию. Также были созданы шаблоны, типичные для большинства проектов, и инструкции, как их заполнять.

How to (step by step)

В первую очередь, нужно составить инвентори — полный список ресурсов проекта. Это виртуальные и железные серверы, облачные ресурсы и сервисы и т.д. Ещё здесь указываются такие характеристики, как количество CPU, размер RAM и ROM, способы доступа к тому или иному ресурсу, если они имеют какие-то особенности. Также в инвентори стоит отразить расположение ресурсов проекта — в каких датацентрах, у каких хостеров или на каких железных серверах они находятся.

Инвентори — очень важная часть инфраструктурной документации, основа основ и фундамент фундаментов. Так что если ресурсов на документацию немного, то это первое и основное, что требуется составить.

Далее нужно определить, делится ли проект на отдельные продукты или подпроекты, или, может быть, в проекте есть разделение на среды, контуры. Например, есть prod — боевой контур, который выполняет основную работу и на который ложится основная нагрузка. А для обеспечения отказоустойчивости может существовать контур reserve. Dev-контур — для разработки, test- и stage-контуры — для тестирования, infra-контур — для обеспечения мониторинга и логирования основных ресурсов и т.д.

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

Распределение серверов по контурам также стоит добавить в инвентори, то есть указать, какой сервер к какому контуру относится.

Следующим шагом нужно понять, к какому условному типу инфраструктуры можно отнести тот или иной его контур. Например, мы выделили такие типы как: LAMP-стек, Kubernetes, облачные инфраструктуры. И в зависимости от этого создали шаблоны для описания контура (рис. 1-3).


Фрагмент шаблона «Описание контура»


Фрагмент шаблона «Описание контура с k8s-кластером»


Фрагмент шаблона «Описание контура с k8s-кластером в Yandex.Cloud»

Обязательно в описании контура прописываем, какие клиентские сервисы и приложения есть, описываем схемы их взаимодействия. Также подробно описываются базы данных — какие используются СУБД, перечень баз, настроены ли репликации и куда/откуда, есть ли исключения для баз или таблиц.

Следующим этапом нужно указать, есть ли резервирование, составить его описание и схему — чтобы все, кто работает с проектом, всегда могли быстро найти информацию о том, что и как зарезервировано. А наличии резервного контура нужно добавить инструкцию по переключению, так как переключение на резерв должно происходить быстро и четко.

Наконец, если в проекте есть IaC, то нужно рассказать как оно работает: указать, какая часть инфраструктуры описана в коде, а какая нет, добавить флоу и правила работы. Также имеет резон указать схему деплоя, добавить описание CI/CD и существующей автоматизации.

Последним обязательным пунктом идёт составление общей схемы инфраструктуры. На ней мы указываем все серверы и работающие на них сервисы, точки входа трафика и проксирование, репликации и синхронизации, а также любые другие взаимосвязи сервисов или контуров.

В первом приближении описание проекта на этом закончено. Далее уже в документацию к каждому проекту будут добавляться свои уникальные инструкции, регламенты и т.п.

Заключение

Инфраструктурная документация — это описание существующего проекта с заданным минимальным уровнем детализации. Этот уровень мы определили, исходя из потребностей наших админов. При этом в документации редко встречается глубокое описание работы какого-то сервиса или клиентского приложения — только если это как-то влияет на саму инфраструктуру, выбор тех или иных сервисов, СУБД и т.п.

Такой подход позволяет составлять стандартизированную документацию для всех проектов, а также увеличивает качество и скорость ее составления. Но несмотря на всю проделанную работу, так как документацию пишет несколько технических писателей, а инструкции добавляют еще и админы, то даже шаблоны не позволили сохранить консистентность и единообразие документации: каждый писал в своем стиле, структура документации не сохранялась, схемы не были единообразными, а оформление статей вообще хромало на обе ноги.

Что с этим делать? Поразмыслив, мы решили составить общий сборник правил: всё о том, как надо писать документацию, начиная от того, какие шрифты и заголовки использовать, и заканчивая полным описанием структуры.

В общем, да — мы пришли к тому, что нам нужен стайлгайд. Драматический рассказ о том, как мы его составляли, читайте в следующей статье.