Хабр, привет!

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

Идеальная документация должна выполнять две основные функции:

1. Освобождение разработчика от дополнительных вопросов: Каждый аспект проекта должен быть четко описан, чтобы разработчик мог сосредоточиться на реализации задач.

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

Так как же все-таки устроена идеальная дока? Она имеет следующую структуру:

1. BRD&SRS.

2. Бизнес-логика

3. UI-логика

4. Продуктовая аналитика

BRD&SRS

BRD&SRS - это документ, объединяющий основные аспекты разработки, включая описание целей проекта, его историю, потребности и ценности, заинтересованных стейкхолдеров, границы проекта и ограничения, функциональные и нефункциональные требования, а также ключевые вопросы и проблемы

1. MAIN GOAL. Тут нам необходимо описать назначение продукта/разработки.

2. Предыстория и краткое изложение сути проекта.

3. Формулировка потребностей и ценность проекта. В этом разделе мы фиксируем потребности, которые удовлетворяются с помощью разработки, и ценности, которые принесет данная разработка. Эффективно использовать в сочетании с BACCM Canvas.

4. Цель проекта по SMART.

5. PEST - анализ конкурентной среды. Анализ внешней среды: политические, экономические, социальные и технологические факторы.

6. Стейкхолдеры продукта. Указываем внутренних и внешних участников проекта. Хорошей практикой является создание матрицы стейкхолдеров или сделать анализ стейкхолдеров с помощью mindmap.

   

7. Границы проекта и ограничения. Определяем границы разработки, ответственность команды (за какие этапы разработки ПО отвечает команда) и ограничения, включая бизнес-правила и регуляторные требования. Будет гораздо легче проанализировать требования от регуляторов, если в предыдущем пункте мы сделали mindmap стейкхолдеров.

8. Функциональные требования и фичи. В данном разделе описываем функционал разрабатываемого продукта. Я предпочитаю описывать их в формате user story с указанием роли пользователя в системе. “Как покупатель, я хочу иметь возможность заказать товар в пункт выдачи.”, “Как администратор пункта выдачи, я хочу иметь возможность отсканировать QR пользователя для получения подробной информации о его товарах. Но можно описать ФТ в формате USE CASE. Также необходимо зафиксировать диаграмму прецедентов, чтобы не забыть или не потерять часть функционала разработки.

9. Требования к интерфейсу. Указываем требования к дизайну и пользовательскому интерфейсу. Данный пункт можно исключить, если дизайн уже разработан.

10. Нефункциональные требования. Список НФТ может быть обширным, но вот некоторые ключевые аспекты:

• Производительность и надежность. Проводим расчеты RPS, пропускной способности и размера хранилища.

• Требования к масштабируемости.

• Требования к безопасности. В последнее время также популярно мнение, что требования к безопасности можно отнести к функциональным требованиям, но по моему опыту, у каждой компании свой подход, поэтому не будет критичным, если отнесем безопасность к НФТ.

11. Вопросы и проблемные моменты.

Таким образом, наш документ объединяет в себе как бизнес-требования, так и технические требования, обеспечивая полное понимание проекта для всех его участников.

Бизнес-логика

Данный раздел включает в себя следующие артефакты:

1. Sequence диаграмма для каждого флоу (смотрим на диаграммы прецедентов)

2. Диаграмма базы данных. Это может быть как и ER диаграмма, так и диаграмма классов.

3. Описание API. Тут зависит от принятых стандартов. Где-то используют Swagger, а где-то пишут ручками по принятым шаблонам. Главное требование - чтобы сервисы были описаны понятно не только для разработчиков, но и для других участников команды.

4. Activity diagram для каждого флоу. Я обычно поступаю следующим образом: создаю типы действий (сетевое действие или запрос, действие пользователя, действие UI, логика SDK) и отмечаю каждое действие определённым цветом. Такой подход отлично отображает флоу пользователя, действия пользователя и системы.

5. Component diagram. Необходимо обновить или создать диаграмму компонентов, отображающую карту сервисов и роль разрабатываемого проекта в ней.

UI логика

Данный раздел служит докой для фронтэнд и мобильных разработчиков и включает в себя следующие артефакты:

1. UI экранов. В данной доке описывается каждый экран. А именно, после получения дизайна, мы для каждого шага делаем скрин экрана, прикладываем в доку и описываем работу данного экрана. То есть описываем какие UI элементы у нас есть, описываем логику их работы и как они реагируют на действия пользователя.

2. Локализация. Тут мы даем название каждому элементу, у которого есть надпись и указываем локализацию на необходимых языках. Данный блок опциональный, так как это зависит от подхода проекта к текстам. Где-то это хардкодится, а где-то хранится в конфигах. Поэтому важно вынести главную мысль данной доки - переиспользование элементов с текстами, а также хранение текста не в коде у разработчика.

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

Продуктовая аналитика и логи

Предпочтительно, чтобы за данный раздел отвечал продуктовый аналитик или product owner. Но жизнь не идеальна, поэтом обсудим что должен содержать данный раздел.

1. Описание используемых метрик. Необходимо описать все этапы воронки пользователя, а также технические и продуктовые метрики.

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

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

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

Также пишу о системном анализе и карьере в it в telegram.