Рецепт совершенной аналитической статьи

Привет, Хабр! Меня зовут Евгений Песков, я работаю аналитиком в команде разработки САПР техпроцессов ВЕРТИКАЛЬ. Рискну поднять тему, из-за которой сломали уже не одну сотню копий, — идеальная аналитическая статья. Возможно ли сконструировать ее шаблон? Чтобы материал был удобен в использовании всем участникам команды разработки, а я, как автор, минимизировал трудоемкость по его написанию и сопровождению.

1a6f2ba575e6cb4729410a40ebe44f77.jpg

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

  • Аналитик:»Я хочу быстро разрабатывать документы, которые будут вызывать только восхищение у тех, кому посчастливится их прочесть. Всем всё будет понятно, и сделано будет ровно так, как написано.»

  • Все участники команды разработки:»Не хотим читать огромный непонятный текст, пытаясь добыть из него нужную информацию. Всё должно быть кратко, по делу, понятно и однозначно».

Противоречий в этих позициях нет. Но есть нюансы, которые произрастают из сложности предмета статьи. Это приводит к нескольким проблемам:

  • большой объём, статья становится избыточной;

  • недостаточность информации, а именно отсутствие данных, необходимых определенным участникам команды (при этом одна и та же статья может быть одновременно избыточной и недостаточной);

  • сложности навигации, когда трудности вызывает поиск нужной информации.

Все это ведет к повышенным трудозатратам на любую работу, касающуюся статьи, будь то её разработка, чтение, корректировка, проверка и так далее).

До того, как оказаться в IT-отрасли, я трудился инженером-конструктором на горно-обогатительном комбинате. Сейчас я могу с уверенностью сказать, что работа инженера-конструктора небольшого проектно-конструкторского отдела и работа аналитика в IT это принципиально один и тот же вид деятельности. Задача и конструктора, и аналитика состоит в том, чтобы описать, ЧТО нужно сделать тем специалистам, которые знают, КАК сделать это ЧТО. Но у конструкторов проблемы решены благодаря отточенной десятками лет ЕСКД (единая система конструкторской документации) — она диктует, как должна быть оформлена конструкторская документация.

97269e8f4634ba675d1792d8509c7faa.png

Конечно, у аналитиков ситуация иная:

  • сама предметная область требует разных подходов для разных задач;

  • работа в командах разработки по своему специфична;

  • для всей отрасли IT характерна высокая скорость изменений.

Поэтому жесткая система, аналогичная ЕСКД, не будет оптимальной.

В апреле 2024 года на внутренней конференции разработчиков компании АСКОН я попытался приблизиться к решению обозначенной проблемы. Для этого был запланирован митап, задачей которого я заявил определение требований ролей команды разработки к аналитике. Все для того, чтобы собрать шаблон аналитической статьи.

040e8ce4efa5469175aef1f8015dee93.png

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

  • коллективно выделить лиц заинтересованных в аналитических статьях;

  • определить требования заинтересованных лиц к аналитической статье;

  • оценить наиболее удобные инструменты и формы представления информации.

Заинтересованные лица

1563deed6e557642059f2f95e60a0f0e.png

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

Сбор требований

Далее, пользуясь формулой User Story, сформулирую требования стейкхолдеров к аналитике.

  1. Я как программист:

    1. хочу, чтобы статья содержала краткое описание предметной области, для общего понимания решаемой функционалом задачи.

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

    3. хочу, чтобы статья содержала критерии приемки для самопроверки.

    4. хочу, чтобы статья содержала данные о быстродействии, удобстве, отказоустойчивости с учётом назначения и ограничений функционала

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

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

    1. хочу, чтобы пользовательские сценарии были описаны исходя из сложных сценариев (большое количество пользователей, параметров, данных)

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

  2. Я как тестировщик:

    1. хочу видеть в статье описание решаемой функционалом пользовательской задачи для понимания соответствия функционала изначальному запросу

    2. хочу видеть в статье описание нештатных ситуаций, для полного понимания действий системы при сложных сценариях

    3. хочу видеть ссылки на не функциональные требования.

  3. Я как аналитик:

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

  4. Я как руководитель команды разработки:

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

    2. хочу видеть в статье приоритизацию фич для планирования

    3. хочу видеть в статье ссылки на связанные задачи в jira, для удобства навигации.

  5. Я как специалист техподдержки:

    1. хочу видеть в статье раздел содержащий описание отличий реализованного функционала от исходной аналитики, для получения достоверной информации о функционале.

  6. Я как маркетолог:

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

    2. если речь идет о новом продукте, то хочу видеть отдельную статью, описывающую концепцию продукта, для применения в маркетинговых материалах

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

Шаблон

Целевая версия

Название или номер версии

Epic

Ссылка на связанный эпик или функцию JIRA

Статус документа

Черновик

Владелец документа

Песков Евгений

Аналитик

Ведущий аналитик

Разработчики

Ведущий разработчик

QA (контроль качества)

Ведущий тестировщик

Оглавление
Структура разделов статьи

Ссылки
На связанные документы/статьи

Введение
Описание проблематики и предварительное описание функционала

Требования

#

Заголовок

User Story

Важность

Примечания

1

Краткое название для истории

Опишите пользователя и что он пытается добиться

Необходимо

Дополнительные соображения и/или примечательные ссылки (запросы, статьи)

2

n

Нефункциональные требования
Блок описания нефункциональных требований.

Пользовательские сценарии
Предусловие: …

#

Действия пользователя

Реакция системы

Макеты интерфейса

1

Нажимает кнопку Х

Поднимает окно Y, в соответствии с макетом справа

2

n

Описание нештатных ситуаций
Описание реакции системы на возможные ошибки и прочее.

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

Заключение

Разумеется, главным положительным итогом митапа стал не шаблон. Наиболее ценным стало понимание запросов коллег, которые они предъявляют к аналитической статье. Именно это необходимо для того, чтобы сделать статью действительно удобной и понятной для всей команды разработки.

За помощь в написании статьи благодарю коллегу Александра Кондусова.

© Habrahabr.ru