Настоящий CTO: думай как технический директор - Алан Уильямсон

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

11.2. Типы документации

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

11.2.1. Протоколы собраний

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

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

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

На каждом собрании назначайте кого-то, кто будет вести заметки, и предусмотрите время для их обработки. Можно вести записи в Google Doc в режиме реального времени, фиксируя ключевые моменты и решения. Если это быстрое собрание, посвященное разбору конкретной задачи, зафиксируйте все договоренности в комментариях к тикету в виде списка.

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

Сообщения в чате (Slack, Microsoft Teams и т. д.) также могут содержать ценную информацию. Пусть члены команды копируют ее и добавляют или в основную базу знаний, или в тикеты. Можно даже настроить ботов или плагины, чтобы вы могли быстро пометить сообщения, которые нужно отправить в отдельное хранилище.

11.2.2. Демонстрации продукта

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

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

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

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

11.2.3. Инструкции по использованию

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

Уровень детализации здесь должен быть достаточным, чтобы любой мог понять и выполнить нужные действия. Недостаточно просто написать: «Обязательно перезапустите компонент XYZ». Как перезапустить XYZ, какие команды нужно вводить и куда, как определить, успешно ли все прошло, и что делать в случае проблем? Такие детали часто пропускаются и хранятся только в чьей-то голове.

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

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

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

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

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

11.2.4. Резервное копирование и восстановление

Часто в документации не уделяется необходимого внимания резервному копированию и восстановлению системы. Необходимо описать не только способ экспорта/импорта базы данных (хотя и это тоже). Речь об информационной системе в целом, от аппаратного обеспечения до операционных систем и ПО.

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

Заметки с полей

Дьявол в деталях

Несколько лет назад я столкнулся с ситуацией, когда попытки настроить новый сервер для генерации уменьшенных версий изображений зашли в тупик, потому что Java-приложение отказывалось работать. Оказалось, что для работы Java-приложения требовалось наличие ImageMagick – это популярная библиотека с открытым исходным кодом. Приложение не выводило достаточно информации для диагностики проблемы, хотя, конечно, должно было бы. Документация или какие-то подсказки также отсутствовали, и для того, чтобы выявить эту зависимость, пришлось декомпилировать приложение.

С ростом популярности контейнеров (таких, как Docker) зависимости на уровне операционной системы теперь обычно описываются как часть процесса сборки. Однако это не отменяет необходимости указать, что от чего зависит. Даже если все находится в контейнерах, необходимо описать, как контейнеры работают и взаимодействуют между собой, чтобы понять, как ими управлять. Должно быть достаточно информации, чтобы любой, кто разбирается в используемых технологиях, мог собрать компоненты системы из исходного кода. Если сейчас это невозможно, то у вас есть информационный долг. Разумеется, документы также необходимо обновлять с каждым релизом, по мере появления новых компонентов и замены или удаления старых.

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

11.2.5. Процесс деплоя

Релизы и обновления систем предприятия должны быть отлажены, предсказуемы и безопасны. Чтобы этого добиться, необходимы соответствующие инструменты и документация. Даже если вы полагаетесь на автоматизированный инструмент оркестрации (такой, как Jenkins), для его настройки в вашей среде все равно требуется руководство.

Оно должно содержать все необходимые шаги