10 KiB
Процессы работы с документацией (AS IS / TO BE)
Основные артефакты системной аналитики
Системные аналитики работают с 3 артефактами:
- бизнес-требованиями
- системной аналитикой
- технической документацией
Бизнес требования
Описывает бизнес и пользовательские требования, пользователькие use case, макеты экранов. Сейчас не всегда оформляется как отдельный документ, часто этот шаг пропускается и требования фиксируются сразу в документе системной аналитики.
Системная аналитика
Документ описыватет изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков. Так же этот документ проходит согласование с экспертами по архитектуре, безопасности, сопровождению.
Может описывать как целиком процесс (в случае реализации с нуля), так и инкремент, который вносит небольшие изменения в существующие процессы.
В данном документе содкржится вся информация по сути вносимых изменений, но отсутствует контекст о текущей реализации системы.
Состоит из разделов:
- Цели - короткое описание какую проблему и для кого решаем.
- Процесс AS IS и TO BE - фокус на изменения с точки зрения бизнес функций, без технической детализации.
- Ограничения - ограничения и допущения в реализации.
- Архитектура - описывает схему уровня контейнеров, основной фокус на интеграции между контейнерами и интеграционные сценарии.
- Функциональные требования - описывают изменения в системе.
- Нефункциональные требования - требования к аудиту, мониторингу, фичетоглам, пользовтелькой аналитике.
Техническая документация
Техническая документация описывает реализацию системы. Эта информация используется командой разработки при проектировании и реализации новых фичей, понимании как работает система. Артефакт живет чуть впереди кода Представялет из себя иерархическую модель документов, сейчас реализованную в конфлюенсе.
Есть несколько типов страниц, каждая из которы описывает определенный тип функциональности
- UI страницы
- API методы
- БД
- Логические блоки
UI страницы
Описывают экран на UI. Декомпозиция Как правило на страницу с описанием выносится целый макет/страница фронтального приложения, с одной основной интеграцией и опционально вспомогательными интеграциями. Например - форма создания сущности. Есть вспомогательгные методы для полученяи правочников, использующихся при заполнении полей на форме, и вызов оснвного метода создания сущности.
Таким образом приложение декомпозируется на отдельные экраны, коотры свызываются между собой последовательно, но сами по себе являются независимыми
Состав описания Все разделы обязательны. Страница с описанием содержит:
- Краткое описание
- Технический use case
- Описание макета с декомпозицией на компоненты + их поведение
- Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
- Нефункциональные требования - фичетоглы и события пользовательской аналитики
API методы
Декомпозиция На каждый метод API заводится отдельная страница. Состав описания Все разделы обязательны. Страница с описанием содержит:
- Краткое описание
- Технический use case
- Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
- Нефункциональные требования - фичетоглы и события пользовательской аналитики
- Контракт метода - описание запроса и ответа. Для ответа так же приводится описание как заполнять поля.
БД
Декомпозиция Сейсас это только странциа с описанием таблица. На каждую таблицу заводится отдельная страница. Состав описания Все разделы обязательны. Страница с описанием содержит:
- Краткое описание
- Таблица с офисанием физической модели данных
Логические блоки
Декомпозиция На отдельную страницу может быть вынесен общий переиспользуемый блок логики. Это позволяет не дублировать его на страницах документации. Как правило соответствует реализации общего компонента в коде. Состав описания Часть разделов в описании может отсутствовать.
- Краткое описание
- Технический use case
- Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
- Нефункциональные требования - фичетоглы и события пользовательской аналитики
Прочие особенности процесса
Описание технических use cases
Сценарий описывает основные шаги процесса в разрезе участников, все технические детали, если их нельзя описать одним предложением, выносятся в разделы функциональных требований, нефункциональных требований, или даются ссылки на другие страницы (как правило это страницы с логическими блоками).
В технических use cases приводятся ссылки на страницы с описнаием вызываемых методов API. Особенно это актуально для страниц фронта, т.к. он использует наши методы API, которые есть в документации. Для интеграций с другими АС как правило приводистя ссылка на описание конфлюенса.
AS IS
Сейчас все артефакты ведутся в конфлюенс. Одна страница содержит описанием одного аретфакта (бизнес требования, системная аналитика, страница документации), страницы организованы иерархически, используюстя ссылки для обозначения связей.
Проблемы:
- документация со временем теряет актуальность
- отсутствие автоматизации
- ручное ведение
TO BE
Целевое состояние:
- аналитик продолжает писать артефакты бизнес-требований и системной аналитики
- агент генерирует и обновляет документацию по странице системной аналитики
- документация становится инженерным артефактом, который ведется в GIT
Форматы
- Markdown
- OpenAPI
- Mermaid / PlantUML
Роль агента
- использование документации как базы знаний - как для ответов на вопросы, так и для проектирования изменений в системе.
- внесение изменений в документацию по артефактам системной аналитики
- генерация из документации спецификаций OPENAPI и JSON-schema