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

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

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


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

Итак, жизненный цикл документации состоит из нескольких этапов, которые могут варьироваться в зависимости от специфики компании и продукта. Но есть в их перечне обязательные:
  1. Инициация
  2. Сбор информации
  3. Написание статей
  4. Проверка
  5. Публикация
  6. Актуализация/Удаление



Инициация


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

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

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


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

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

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

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

Проверка


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

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


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

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

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

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

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

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

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


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



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



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

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


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

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


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

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

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


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

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

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

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


И всё же — что если обойтись без технических писателей и отдать всё в одни чьи-то руки из числа админствующих коллег? Это чревато рядом трудностей:
  • документация не ведется совсем или ведется частично,
  • знания хранятся у одного человека,
  • «трудности перевода» в понимании изложенного другими сотрудниками,
  • не описаны (пропущены) важные детали.

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

Вывод


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

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

Комментарии (1)


  1. rasperepodvipodvert
    03.12.2022 15:21

    Прочитал, и как-то вроде обо всем и ни о чем...