Восстановление технической документации

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

Коротко о задаче

Документация исчезает одинаково. Сначала её не пишут, потому что «система маленькая и всё понятно». Потом не пишут, потому что горят сроки. Потом система вырастает, и написать сразу всё уже страшно.

Отсутствие документов не мешает, пока система в руках тех, кто её делал. Проблемы приходят вместе с изменениями состава.

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

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

Мы восстанавливаем и то, и другое.

Что входит в услугу

• Разбор системы

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

• Описание архитектуры

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

• Порядок развёртывания

Пошаговое описание установки на чистую среду: зависимости, настройки, переменные окружения, порядок запуска, проверка работоспособности. Проверяем инструкцию на практике — разворачиваем по ней сами.

• Описание конфигурации

Перечень параметров с назначением, допустимыми значениями и последствиями изменения. Отдельно фиксируем значения, установленные не по умолчанию, и причину.

• Схема данных

Описание структуры базы, назначения таблиц и ключевых полей, связей, правил хранения и архивирования.

• Регламенты эксплуатации

Резервное копирование и восстановление, обновление, мониторинг, действия при типовых сбоях, порядок предоставления доступа.

• Инструкции пользователей

Руководства по ролям, написанные языком пользователя, а не разработчика.

• Документация для регулируемых отраслей

Ретроспективное описание требований пользователя, функциональных и технических спецификаций, матрицы прослеживаемости, обоснование решений. Смотрите {{ссылка: Валидация компьютеризированных систем по GAMP 5}} и {{ссылка: Разработка документации по IT-процессам}}.

Что это даёт заказчику

• Снятая зависимость от людей. Уход сотрудника перестаёт быть аварией.
• Быстрое погружение новых. Разработчик или администратор выходит на рабочий темп за дни, а не за месяцы.
• Возможность сменить подрядчика. Есть что передать, и передача не превращается в отдельный проект.
• Проверенная инструкция развёртывания. Мы разворачиваем систему по собственному документу, поэтому он работает, а не выглядит правдоподобно.
• Готовность к аудиту. Для регулируемых отраслей документация закрывает один из первых вопросов проверяющего.
• Найденные проблемы. Разбор системы попутно вскрывает то, о чём не знали: неиспользуемые компоненты, устаревшие зависимости, расхождения между кодом и запущенной версией.

Как мы работаем

Начинаем с определения назначения документов. Комплект для передачи подрядчику, комплект для аудита и комплект для обучения пользователей — три разных документа, и писать их одинаково бессмысленно.

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

Отдельно проговариваем поддержание в актуальном состоянии. Документ, который перестают обновлять, через год снова становится бесполезным, поэтому обновление документации имеет смысл встроить в процесс выпуска изменений. Смотрите {{ссылка: Техническая поддержка и развитие собственного продукта заказчика}}.

Наш опыт

Мы работаем в регулируемых отраслях с 2022 года и готовили документацию, которую предъявляли на проверках: на системах нашей разработки заказчики прошли более тридцати аудитов клиентов и более десяти инспекций регуляторов.

Мы также восстанавливали устройство чужих систем при их приёме на сопровождение и при миграциях: разбор кода без документации — часть каждого такого проекта. Смотрите {{ссылка: Приём проекта после предыдущего подрядчика}}.

Расскажите, на какую систему нужны документы и для чего они предназначены. Начнём с разбора и предложим состав комплекта.