Жизненный цикл инфраструктурной документации: документируй это от заката до рассвета
О том, что такое инфраструктурная документация и чем она полезна как аутсорсерам, так и владельцам проектов, мы писали в предыдущей статье. Теперь настало время поговорить о грустном: инфраструктурная документация не вечна… Мало того, что она в принципе изменчивая натура, так ещё и случается так, что жизненный цикл её конечен. Или нет?…
Расскажем сегодня, почему не стоит пугаться словосочетания «жизненный цикл» и может ли он действительно закончиться, или всё новое — хорошо забытое?…
Документация не бывает статичной; она всегда претерпевает изменения — обновляется, удаляется, восстанавливается или меняет структуру. Эти изменения и составляют жизненный цикл инфраструктурной документации. Его необходимо сформировать как процесс и приучать к нему сотрудников.
Итак, жизненный цикл документации состоит из нескольких этапов, которые могут варьироваться в зависимости от специфики компании и продукта. Но есть в их перечне обязательные:
- Инициация
- Сбор информации
- Написание статей
- Проверка
- Публикация
- Актуализация/Удаление
Инициация
Для запуска жизненного цикла необходим триггер. Толчком может послужить, например, добавление каких-то компонентов в инфраструктуру, внесение крупных изменений в код приложения и т.п.
Триггер должен быть обязательной частью процесса. То есть чтобы при добавлении компонента в код запускался процесс обновления документации.
Сбор информации
Основной этап создания статей — это сбор информации. От того, как сформирован путь получения данных, зависит конечный вид документации.
Как это делаем мы? — Разговариваем :-) Подготавливаем список вопросов и опрашиваем всех, кто знаком со спецификой проекта. На основе собранной информации формируем структуру статей. Правильная структура логически упорядочена, разбита на разделы и подразделы, включает в себя элементы форматирования текста.
Но в этом простом, на первый взгляд, рецепте бывают свои нюансы:
- недостаточный объем информации;
- незнание специфики проекта;
- неактуальные сведения.
Техрайтеры часто сталкиваются с незнанием всей специфики, что отрицательно сказывается на работе. А инженеры, владеющие информацией, в свою очередь, страдают так называемым «проклятием знания», когда многие вещи кажутся им очевидными и они не считают их достойными упоминания, хотя, конечно, детали важны.
Проверка
После написания статьи направляются на рецензию, далее публикуются или вносятся исправление. По выявленным недостатками заново обращаемся к знающим проект людям с вопросами. Важно, чтобы документацию читали и оценивали те люди, которые с ней будут работать.
Хранение документации
База знаний — это продуманное пространство для хранения знаний с возможностью совместной работы. Её можно вести в разных источниках — вот некоторые из них:
- GitBook
- Archbee
- Confluence
- Notion
- Google-документ
Наша компания работает с Confluence, поэтому ниже описаны его достоинства. Хотя для для всех российских пользователей это будет актуально, но всё же среди наших читателей немало тех, у кого остаётся доступ к системе.
Несомненный плюс Confluence в том, что предоставляется выбор, где будет размещаться вики-система — в облаке или в формате дата-центра.
Возможность создания разных пространств для хранения информации помогает структурировать документацию. Для наших объемов и информации та иерархическая структура, которую дает Confluence, очень подходит.
Кроме того, здесь можно использовать шаблоны, как готовые, так и собственные, что увеличивает эффективность работы и экономит ресурсы.
Есть и минусы. Например, поисковая система. Её работа не удовлетворяет потребностям наших инженеров, так что пришлось разработать систему тэгов и написать телеграм-бот.
Актуализация и сроки устаревания статей
Поддержание актуальности статей — одна из основных задач. Или проблем — как посмотреть. При неэффективном подходе можно затратить слишком много времени на обновления. Поэтому стоит проанализировать, на какие статьи уходит больше всего времени и как его можно сократить.
По графику выше видно, что самое большое количество изменений было внесено перед новым годом. Можно предположить, что самые масштабные работы по инфраструктуре проекта проводятся именно в это время.
Второй график показывает, что самые частые правки в статьи с тегом guide вносились в феврале. Следовательно, для новых инфраструктур, введенных в эксплуатацию в декабре, руководства пишутся в январе.
В каких случаях нужно обновление инструкций/документации
Необходимость в этом возникает при:
- добавлении или удалении серверов, продуктов и приложений,
- переезде в новый ДЦ или облако,
- использовании новых инструментов.
Как часто нужно вносить изменения в инструкции?
Тут нет чётко заданных временнЫх параметров. Частота обновлений статей зависит от нескольких факторов:
- масштаб проекта,
- качества вносимых изменений,
- частоты вносимых изменений.
Для проектов, требующих частой актуализации, лучше запланировать время для обновления и делать его в конце недели — как раз накопится нужный объем информации, и дежурные смогут использовать актуализированные статьи в выходные.
Кем обновляются статьи
В управлении документацией важно четко обозначить зону ответственности, все зависит от того, как выстроен процесс и нуждается ли в техническом писателе. Последний готовит документацию, которая соответствует запросам и потребностям целевой аудитории.
Однако существенный минус техрайтеров в том, что они не разрабатывают инфраструктуры, т.е не участвуют в том, о чем пишут. С другой стороны, возложив роль технического писателя на инженеров, которые как раз участвуют в построении инфраструктуры и разработке продукта, мы получим риск несвоевременного обновления статей. Потому как — будем честны — на практике коллеги-админы уделяют этим задачам мало внимания. Им не хватает времени и порой простого интереса заниматься документацией, да и не каждый умеет сформулировать свои мысли в читабельную статью.
В нашей компании техрайтеры не только пишут документацию, но и внедряют процессы управления знаниями, получая информацию от инженеров. Составляют различные шаблоны с использованием стайлгайда, формируют и поддерживают структуру базы знаний, контролируют актуальность статей. Вот перечень обязательных навыков для техписателей в ITSumma:
- сбор сведений о проекте, их структурирование и анализ,
- сбор технических характеристик,
- создание графики: схемы, диаграммы, гистограммы,
- перевод документов на иностранные языки.
Проблемы монополизации
И всё же — что если обойтись без технических писателей и отдать всё в одни чьи-то руки из числа админствующих коллег? Это чревато рядом трудностей:
- документация не ведется совсем или ведется частично,
- знания хранятся у одного человека,
- «трудности перевода» в понимании изложенного другими сотрудниками,
- не описаны (пропущены) важные детали.
Сотрудник, знающий проект, но не являющийся техническим писателем, может упустить важные детали в статьях. Ему сложно в одиночку создать правильную и понятную структуру, в которой легко найти интересующую пользователя информацию. Плюс, в тексте могут присутствовать грамматические ошибки и жаргонизмы, а это не упрощает восприятие. Ну и главное: когда документация ведется, одним человеком, знающим проект, это неизбежно приводит к потере знаний и меньшему объему фиксируемой информации.
Так что же жизненный цикл? — О, не переживайте: если у вас есть желание и возможность выделить ресурсы на грамотную организацию работы с инфраструктурной документацией, она будет жить и развиваться столько же, сколько и ваш проект. И с течением времени в ней будет накапливаться всё больше исторических данных и артефактов, которые всегда помогут найти путь к решению даже самой сложной проблемы, если её корень кроется где-то в инфраструктуре.
Просто «документируй это» ;-)
