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

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

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

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

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

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

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