Привет, Хабр! Меня зовут Евгений Песков, я работаю аналитиком в команде разработки САПР техпроцессов ВЕРТИКАЛЬ. Рискну поднять тему, из‑за которой сломали уже не одну сотню копий, — идеальная аналитическая статья. Возможно ли сконструировать ее шаблон? Чтобы материал был удобен в использовании всем участникам команды разработки, а я, как автор, минимизировал трудоемкость по его написанию и сопровождению.
Зачастую аналитическая статья становится точкой конфронтации между аналитиком и остальными участниками команды разработки. Хотя их пожелания к статье явно не противоречат друг другу...
Аналитик: «Я хочу быстро разрабатывать документы, которые будут вызывать только восхищение у тех, кому посчастливится их прочесть. Всем всё будет понятно, и сделано будет ровно так, как написано.»
Все участники команды разработки: «Не хотим читать огромный непонятный текст, пытаясь добыть из него нужную информацию. Всё должно быть кратко, по делу, понятно и однозначно».
Противоречий в этих позициях нет. Но есть нюансы, которые произрастают из сложности предмета статьи. Это приводит к нескольким проблемам:
большой объём, статья становится избыточной;
недостаточность информации, а именно отсутствие данных, необходимых определенным участникам команды (при этом одна и та же статья может быть одновременно избыточной и недостаточной);
сложности навигации, когда трудности вызывает поиск нужной информации.
Все это ведет к повышенным трудозатратам на любую работу, касающуюся статьи, будь то её разработка, чтение, корректировка, проверка и так далее).
До того, как оказаться в IT‑отрасли, я трудился инженером‑конструктором на горно‑обогатительном комбинате. Сейчас я могу с уверенностью сказать, что работа инженера‑конструктора небольшого проектно‑конструкторского отдела и работа аналитика в IT это принципиально один и тот же вид деятельности. Задача и конструктора, и аналитика состоит в том, чтобы описать, ЧТО нужно сделать тем специалистам, которые знают, КАК сделать это ЧТО. Но у конструкторов проблемы решены благодаря отточенной десятками лет ЕСКД (единая система конструкторской документации) — она диктует, как должна быть оформлена конструкторская документация.
Конечно, у аналитиков ситуация иная:
сама предметная область требует разных подходов для разных задач;
работа в командах разработки по своему специфична;
для всей отрасли IT характерна высокая скорость изменений.
Поэтому жесткая система, аналогичная ЕСКД, не будет оптимальной.
В апреле 2024 года на внутренней конференции разработчиков компании АСКОН я попытался приблизиться к решению обозначенной проблемы. Для этого был запланирован митап, задачей которого я заявил определение требований ролей команды разработки к аналитике. Все для того, чтобы собрать шаблон аналитической статьи.
Разумеется, к вопросу решено было подойти аналитически:
коллективно выделить лиц заинтересованных в аналитических статьях;
определить требования заинтересованных лиц к аналитической статье;
оценить наиболее удобные инструменты и формы представления информации.
Заинтересованные лица
По сути, все участники команды на определенных этапах работы взаимодействуют с аналитикой, поэтому смело вносим в список всех от программистов до технических писателей. Да и даже за пределами команды разработки есть стейкхолдеры.
Сбор требований
Далее, пользуясь формулой User Story, сформулирую требования стейкхолдеров к аналитике.
Я как программист:
1. хочу, чтобы статья содержала краткое описание предметной области, для общего понимания решаемой функционалом задачи.
2. хочу, чтобы статья содержала краткие сведения о связи нового функционала с существующим, для определения вопросов касающихся архитектуры.
3. хочу, чтобы статья содержала критерии приемки для самопроверки.
4. хочу, чтобы статья содержала данные о быстродействии, удобстве, отказоустойчивости с учётом назначения и ограничений функционала
5. хочу, чтобы статья была отформатирована на удобные для восприятия блоки для удобства работы с ней
6. хочу, чтобы статья содержала подробные пользовательские сценарии (возможно с макетами интерфейса), для полного понимания разрабатываемого функционального блока
1. хочу, чтобы пользовательские сценарии были описаны исходя из сложных сценариев (большое количество пользователей, параметров, данных)
7. хочу, чтобы в статье описывались наименования переменных, соответствующие предметной области, чтобы избежать некорректного нейминга со стороны программиста.Я как тестировщик:
хочу видеть в статье описание решаемой функционалом пользовательской задачи для понимания соответствия функционала изначальному запросу
хочу видеть в статье описание нештатных ситуаций, для полного понимания действий системы при сложных сценариях
хочу видеть ссылки на не функциональные требования.
Я как аналитик:
хочу, чтобы статья содержала краткие сведения о связи нового функционала с существующим, для удобства поиска информации при разработке аналитики
Я как руководитель команды разработки:
хочу видеть в статье разбивку на блоки работ, для планирования
хочу видеть в статье приоритизацию фич для планирования
хочу видеть в статье ссылки на связанные задачи в jira, для удобства навигации.
Я как специалист техподдержки:
хочу видеть в статье раздел содержащий описание отличий реализованного функционала от исходной аналитики, для получения достоверной информации о функционале.
Я как маркетолог:
хочу видеть в статье описание исходной проблематики, для применения в маркетинговых материалах
если речь идет о новом продукте, то хочу видеть отдельную статью, описывающую концепцию продукта, для применения в маркетинговых материалах
хочу видеть подробные пользовательские сценарии, для выбора наиболее ярких вариантов использования для применения в маркетинговых материалах
Шаблон
Целевая версия | Название или номер версии |
|---|---|
Epic | Ссылка на связанный эпик или функцию JIRA |
Статус документа | Черновик |
Владелец документа | Песков Евгений |
Аналитик | Ведущий аналитик |
Разработчики | Ведущий разработчик |
QA (контроль качества) | Ведущий тестировщик |
Оглавление
Структура разделов статьи
Ссылки
На связанные документы/статьи
Введение
Описание проблематики и предварительное описание функционала
Требования
# | Заголовок | User Story | Важность | Примечания |
|---|---|---|---|---|
1 | Краткое название для истории | Опишите пользователя и что он пытается добиться | Необходимо | Дополнительные соображения и/или примечательные ссылки (запросы, статьи) |
2 |
|
|
|
|
... |
|
|
|
|
n |
|
|
|
|
Нефункциональные требования
Блок описания нефункциональных требований.
Пользовательские сценарии
Предусловие:…
# | Действия пользователя | Реакция системы | Макеты интерфейса |
|---|---|---|---|
1 | Нажимает кнопку Х | Поднимает окно Y, в соответствии с макетом справа | |
2 |
|
|
|
... |
|
|
|
n |
|
|
|
Описание нештатных ситуаций
Описание реакции системы на возможные ошибки и прочее.
Отличие от фактической реализации
Описание нюансов реализации, которые не соответствуют аналитике
Заключение
Разумеется, главным положительным итогом митапа стал не шаблон. Наиболее ценным стало понимание запросов коллег, которые они предъявляют к аналитической статье. Именно это необходимо для того, чтобы сделать статью действительно удобной и понятной для всей команды разработки.
За помощь в написании статьи благодарю коллегу Александра Кондусова.
