О том, что такое инфраструктурная документация и чем она полезна как аутсорсерам, так и владельцам проектов, мы писали в предыдущей статье. Теперь настало время поговорить о грустном: инфраструктурная документация не вечна… Мало того, что она в принципе изменчивая натура, так ещё и случается так, что жизненный цикл её конечен. Или нет?..

Расскажем сегодня, почему не стоит пугаться словосочетания «жизненный цикл» и может ли он действительно закончиться, или всё новое — хорошо забытое?..

Документация живёт и побеждает

Документация не бывает статичной; она всегда претерпевает изменения — обновляется, удаляется, восстанавливается или меняет структуру. Эти изменения и составляют жизненный цикл инфраструктурной документации. Его необходимо сформировать как процесс и приучать к нему сотрудников.

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

1. Инициация
2. Сбор информации
3. Написание статей
4. Проверка
5. Публикация
6. Актуализация/Удаление

Инициация

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

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

Сбор информации

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

Как это делаем мы? — Разговариваем :-) Подготавливаем список вопросов и опрашиваем всех, кто знаком со спецификой проекта. На основе собранной информации формируем структуру статей. Правильная структура логически упорядочена, разбита на разделы и подразделы, включает в себя элементы форматирования текста.

Но в этом простом, на первый взгляд, рецепте бывают свои нюансы:

• недостаточный объем информации;
• незнание специфики проекта;
• неактуальные сведения.

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

Проверка

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

Хранение документации

База знаний — это продуманное пространство для хранения знаний с возможностью совместной работы. Её можно вести в разных источниках — вот некоторые из них:

• GitBook
• Archbee
• Confluence
• Notion
• Google-документ

Наша компания работает с Confluence, поэтому ниже описаны его достоинства. Хотя для для всех российских пользователей это будет актуально, но всё же среди наших читателей немало тех, у кого остаётся доступ к системе.

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

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

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

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

Актуализация и сроки устаревания статей

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



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



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

В каких случаях нужно обновление инструкций/документации

Необходимость в этом возникает при:

• добавлении или удалении серверов, продуктов и приложений,
• переезде в новый ДЦ или облако,
• использовании новых инструментов.

Как часто нужно вносить изменения в инструкции?

Тут нет чётко заданных временнЫх параметров. Частота обновлений статей зависит от нескольких факторов:

• масштаб проекта,
• качества вносимых изменений,
• частоты вносимых изменений.

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

Кем обновляются статьи

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

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

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

• сбор сведений о проекте, их структурирование и анализ,
• сбор технических характеристик,
• создание графики: схемы, диаграммы, гистограммы,
• перевод документов на иностранные языки.

Проблемы монополизации

И всё же — что если обойтись без технических писателей и отдать всё в одни чьи-то руки из числа админствующих коллег? Это чревато рядом трудностей:

• документация не ведется совсем или ведется частично,
• знания хранятся у одного человека,
• «трудности перевода» в понимании изложенного другими сотрудниками,
• не описаны (пропущены) важные детали.

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

Вывод

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

Просто «документируй это» ;-)