Документация системы
Система должна
быть понятна
Разработка системы не заканчивается в момент, когда решение прошло предусмотренные проверки и запущено в рабочей среде. Для дальнейшей эксплуатации важно понимать, из каких компонентов состоит система, как они связаны между собой, где находятся данные, какие внешние сервисы используются и какие зависимости необходимо учитывать.
Техническую документацию готовим одновременно с разработкой системы. В ней описываем архитектуру, компоненты, интеграции и настройки, необходимые для эксплуатации и дальнейшего развития решения.
Как устроена
система
Описываем архитектуру решения: состав компонентов, назначение каждого из них, взаимосвязи и порядок взаимодействия. Уровень детализации зависит от сложности системы и задач её дальнейшего развития.
В зависимости от проекта описываем приложения и сервисы, базы данных, очереди и механизмы обработки данных, интеграционные компоненты, внешние зависимости и точки взаимодействия с существующими системами заказчика. Для сложных решений отдельно фиксируются уровни архитектуры и связи между ними — от общей схемы решения до конкретных технических компонентов.
Отдельно описываем границы системы и маршруты передачи данных: источники информации, места обработки и хранения, компоненты-получатели и интерфейсы взаимодействия.
Как системы
взаимодействуют
Описываем взаимодействие решения с корпоративными системами, внешними сервисами и инфраструктурой заказчика. Указываем участвующие системы, состав передаваемых данных и используемые механизмы обмена.
В зависимости от архитектуры описываем API, webhooks, очереди сообщений, базы данных, файловый обмен и другие используемые механизмы интеграции.
Такой уровень описания позволяет техническим специалистам заказчика понимать не только наличие интеграции, но и принцип её работы внутри общей архитектуры системы.
Где работает
система
Описываем инфраструктуру, в которой работает решение, и требования к её настройке. Состав необходимых ресурсов зависит от задач проекта, требований к производительности, безопасности и доступности, а также от существующей инфраструктуры заказчика.
Данные и их
движение
// STORAGE_COMPLIANCE: VERIFIED
Описываем источники данных, места их обработки и хранения, а также компоненты, через которые проходит информация. Для интеграционных и корпоративных решений отдельно указываем, какие системы отвечают за получение, изменение и передачу данных.
В зависимости от проекта описываются используемые базы данных и хранилища, основные сущности и структуры данных, источники и получатели информации, механизмы передачи и обработки. Если данные проходят несколько этапов обработки, фиксируется последовательность этих операций и связь между соответствующими компонентами системы.
Отдельно могут быть отражены требования к доступу, резервированию, срокам хранения и передаче данных между внутренними и внешними системами — в соответствии с архитектурой и условиями конкретного проекта.
Для решений с ИИ-компонентами документация может включать описание источников корпоративных знаний, используемых хранилищ, механизмов поиска и передачи контекста, а также границ взаимодействия ИИ-компонентов с внутренними системами и данными.
Такое описание позволяет техническим специалистам понимать не только структуру хранения, но и полный жизненный цикл данных внутри разработанного решения.
Доступ к компонентам
системы
Описываем, как пользователи, сервисы и технические компоненты получают доступ к системе. Состав документации зависит от архитектуры решения и требований к его эксплуатации.
Как система используется
после запуска
OPERATION_MODE: STEADY_RUN
Отдельный раздел документации посвящён повседневной эксплуатации системы. В нём описываем основные технические операции и действия, необходимые для поддержания её работы.
В зависимости от проекта это может включать порядок запуска и остановки компонентов, обновление сервисов, конфигурацию, проверку состояния системы, работу с логами, диагностику типовых ошибок и действия при недоступности отдельных компонентов или внешних зависимостей.
Что было проверено
В документации указываем, какие проверки прошло решение перед запуском и в каких условиях проводилось тестирование.
В зависимости от проекта документируются проверенные бизнес-сценарии, интеграционные взаимодействия, автоматические действия, обработка ошибок, работа с неполными или некорректными данными и поведение системы при недоступности отдельных компонентов.
Для сложных решений могут фиксироваться результаты отдельных тест-кейсов, обнаруженные отклонения, выполненные корректировки и ограничения, которые необходимо учитывать при дальнейшей эксплуатации.
Результаты тестирования показывают, какие сценарии проверены, какие ограничения выявлены и что необходимо повторно протестировать после внесения изменений.
Передача заказчику
После разработки и тестирования передаём заказчику техническую документацию, состав которой зависит от архитектуры системы, инфраструктуры и условий дальнейшей эксплуатации.
В комплект могут входить схемы архитектуры и интеграций, описание инфраструктуры и структур данных, настройки компонентов и инструкции по эксплуатации.
При необходимости разработанное решение и соответствующие технические материалы могут быть переданы другой технической команде для дальнейшей эксплуатации или развития.
Документация под
конкретную систему
Состав документации зависит от архитектуры системы, количества интеграций, инфраструктуры и условий эксплуатации. Поэтому для каждого проекта подбираем необходимые технические материалы, а не используем одинаковый комплект документов.
Для локальной автоматизации это может быть компактный комплект материалов, описывающий реализованный процесс, интеграции и необходимые настройки. Для крупной корпоративной системы документация может охватывать архитектуру, инфраструктуру, информационные потоки, базы данных, API, доступы, эксплуатационные процедуры, результаты тестирования и другие технические аспекты решения.
При изменении или расширении решения соответствующие технические материалы могут дополняться в рамках дальнейших работ или сопровождения.
Документация как основа
развития
При дальнейшем развитии системы документация позволяет опираться на существующую архитектуру и связи между компонентами, не изучая их заново.
При добавлении интеграций, автоматизации новых процессов или подключении ИИ-компонентов инженеры используют существующие схемы и технические описания для проектирования изменений.
Если развитие системы выполняет LOG-AI, документация используется инженерной командой вместе с результатами предыдущих работ. Если дальнейшие изменения выполняет внутренняя команда заказчика или другой подрядчик, технические материалы позволяют опираться на уже реализованную архитектуру и существующие интеграции.
Что относится
к системе
Документация описывает разработанное решение и его компоненты, но не заменяет технические материалы внешних систем, инфраструктуры и сервисов, которые не входят в состав проекта.
В описании отражаются компоненты, интеграции и зависимости, которые входят в реализованную архитектуру. Для внешних систем фиксируется необходимая информация о способе взаимодействия с ними, используемых интерфейсах и ограничениях, влияющих на работу решения.
Это позволяет определить, какие компоненты входят в решение, от каких внешних систем оно зависит и какие условия необходимы для его работы.
Техническая документация
начинается с проектирования
Состав технической документации определяем на этапе проектирования. Это позволяет сразу учитывать архитектуру, инфраструктуру, интеграции и требования к эксплуатации системы.
К запуску подготавливаем описание архитектуры, интеграций, инфраструктуры и настроек, необходимых для эксплуатации и дальнейшего развития системы.