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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Далее, пользуясь формулой 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. хочу видеть подробные пользовательские сценарии, для выбора наиболее ярких вариантов использования для применения в маркетинговых материалах

Шаблон

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

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

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

Требования

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

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

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

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

Заключение

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

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