Что такое техническая документация? Зачем она нужна? Вопросы интересные. Если отвечать на них бюрократическим языком, то получится длинно, важно и непонятно. Поэтому мы попробуем ответить по-простому.
Больше полезных статей про IT в нашем канале: https://t.me/itsumma
Техническая документация — это некоторое количество документов, в которых содержится информация об устройстве продукта или системы, как ими пользоваться, какие могут быть проблемы и как их решать, схемах работы, взаимодействии разных частей и многое другое.
Зачастую под ней понимают описание именно программного продукта и его работы. Однако то, где это ПО работает, в какой инфраструктуре развернуто, тоже имеет большое значение. В этой статье расскажем об особенностях составления инфраструктурной документации, с какими сложностями мы сталкивались и как их решали.
Чем полезна техническая документация?
Наличие подробной документации позволяет сэкономить время при работе с клиентской инфраструктурой. Например, чтобы быстро понять, что и где расположено, есть ли репликации у баз данных, настроен ли мониторинг и где хранятся логи.
Документация помогает как текущим сотрудникам при проведении плановых и экстренных работ, так и новым сотрудникам в процессе онбординга. Новый сотрудник тем быстрее приступит к своим обязанностям, чем быстрее вникнет в работу, в том числе разберется, как построена и из чего состоит инфраструктура проекта.
Документация помогает при внедрении глобальных инфраструктурных изменений, например, при переезде с одного технологического стека на другой. Благодаря ей во время переноса инженеры смогут в любой момент максимально быстро получить необходимую информацию.
Она дает не только чёткое представление, из чего состоит система, но и помогает заметить лишние компоненты. Согласитесь, довольно обидно платить деньги за те ресурсы, которые потеряли свою актуальность и не используются. А в документации такое сразу увидишь.
Что обязательно должно быть в инфраструктурной документации?
У всех проектов инфраструктуры уникальны. У первого есть только один сервер, на котором крутится и база, и веб-сервер, и, допустим, почтовый клиент. А у второго — десятки серверов, каждый из которых отвечают за свою роль. В третьем всё крутится на железных серверах и виртуалках, а в четвёртом часть проекта или он весь расположены в облаке.
А ещё где-то там настроен кластер Kubernetes, который конфигурируется при помощи Ansible… В общем, для составлении документации становится сложно.
Поэтому мы выделили несколько элементов, которые обязательно должны в технических “летописи” проекта.
Инвентори — полный список ресурсов
Это виртуальные и железные серверы, облачные ресурсы и сервисы и т.д. Ещё здесь указываются такие характеристики, как количество CPU, размер RAM и ROM, способы доступа к тому или иному ресурсу, если они имеют какие-то особенности. Также в инвентори стоит отразить расположение ресурсов проекта — в каких датацентрах, у каких хостеров или на каких железных серверах они находятся.
Инвентори — очень важная часть инфраструктурной документации, основа основ и фундамент фундаментов. Так что если ресурсов на документацию немного, то это первое и основное, что требуется составить.
Далее нужно определить, делится ли проект на отдельные продукты или подпроекты, или, может быть, в проекте есть разделение на среды, контуры. Например, есть prod — боевой контур, который выполняет основную работу и на который ложится основная нагрузка. А для обеспечения отказоустойчивости может существовать контур reserve. Dev-контур — для разработки, test- и stage-контуры — для тестирования, infra-контур — для обеспечения мониторинга и логирования основных ресурсов и т.д.
Разделение по контурам и продуктам у каждого проекта своё, но уже то, что такое разделение можно провести, позволяет быстрее разобраться в инфраструктуре и понять взаимосвязи сервисов. Распределение серверов по контурам также стоит добавить в инвентори, то есть указать, какой сервер к какому контуру относится.
Типы инфраструктуры — по контурам
Следующим шагом нужно понять, к какому условному типу инфраструктуры можно отнести тот или иной его контур. Например, мы выделили такие типы как: LAMP-стек, Kubernetes, облачные инфраструктуры. И в зависимости от этого создали шаблоны для описания контура (рис. 1-3).
Обязательно в описании контура прописываем, какие клиентские сервисы и приложения есть, описываем схемы их взаимодействия. Также подробно описываются базы данных — какие используются СУБД, перечень баз, настроены ли репликации и куда/откуда, есть ли исключения для баз или таблиц.
Схема и описание системы резервирования
Следующим этапом нужно указать, есть ли резервирование, составить его описание и схему — чтобы все, кто работает с проектом, всегда могли быстро найти информацию о том, что и как зарезервировано. А наличии резервного контура нужно добавить инструкцию по переключению, так как переключение на резерв должно происходить быстро и четко.
Если в проекте есть IaC, то нужно описать как он работает: указать, какая часть инфраструктуры описана в коде, а какая нет, добавить флоу и правила работы. Также имеет резон указать схему деплоя, добавить описание CI/CD и существующей автоматизации.
Общая схема инфраструктуры
На ней мы указываем все серверы и работающие на них сервисы, точки входа трафика и проксирование, репликации и синхронизации, а также любые другие взаимосвязи сервисов или контуров.
В первом приближении описание проекта на этом закончено. Далее уже в документацию к каждому проекту будут добавляться свои уникальные инструкции, регламенты и т.п.
Заключение
Инфраструктурная документация — это описание существующего проекта с заданным минимальным уровнем детализации. Этот уровень мы определили, исходя из потребностей наших админов. При этом в документации редко встречается глубокое описание работы какого-то сервиса или клиентского приложения — только если это как-то влияет на саму инфраструктуру, выбор тех или иных сервисов, СУБД и т.п.
Такой подход позволяет составлять стандартизированную документацию для всех проектов, а также увеличивает качество и скорость ее составления. Но несмотря на всю проделанную работу, документацию пишет несколько технических писателей, а инструкции добавляют еще и админы. Поэтому даже шаблоны не позволили сохранить консистентность и единообразие документации: каждый писал в своем стиле, структура документации не сохранялась, схемы не были единообразными, а оформление статей вообще хромало на обе ноги.
Что с этим делать? Поразмыслив, мы решили составить общий сборник правил: всё о том, как надо писать документацию, начиная от того, какие шрифты и заголовки использовать, и заканчивая полным описанием структуры.
В общем, да — мы пришли к тому, что нам нужен стайлгайд. Драматический рассказ о том, как мы его составляли, читайте в другой статье.
