127 lines
10 KiB
Markdown
127 lines
10 KiB
Markdown
# Процессы работы с документацией (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
|
|
|