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

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

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

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

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

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

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