Хабр, привет!
Меня расстраивает несправедливость в мире IT: для новичков-разработчиков есть куча пошаговых инструкций, о там как разработать API или мобильное приложение. Хочу немного выровнять баланс вселенной, поэтому написал небольшой гайд для аналитиков для составления документации.
В прошлой статье я представил шаблон, а теперь заполнил его для фичи «Экспресс-доставка товара в маркетплейсе». Моя цель — показать, как можно вести документацию и как правильно заполнять этот шаблон.
Примечание. Хочу отметить, что требования для данной фичи не были глубоко продуманы и проработаны, это всего лишь пример, который может содержать недочеты.
Что вы найдете в этой статье?
Полный шаблон документации.
Пояснения для заполнения каждого раздела.
Пример заполнения данного шаблона.
Ссылки на пустой и заполненный шаблон в Notion для удобного копирования в ваше пространство.
Для кого эта статья?
Для новичков, которые хотят ознакомиться с основами ведения документации.
Для тех, кому надо построить документацию с нуля и они ищут существующие шаблоны и практики.
Для тех, кто просто хочет посмотреть на другие подходы к документации или добавить что-то новое в свою документацию.
Что включает в себя данный шаблон?
BRD&SRS.
Бизнес-логика. Спецификация бэкенда.
UI-логика. Документация фронтэнда.
Продуктовая аналитика.
В каждой главе содержатся шаблон с руководством по заполнению (теория) и пример заполнения шаблона, они в отдельных блоках под спойлером. Надеюсь, гайд с примерами будет полезен вам в работе и поможет в создании качественной документации!
BRD&SRS
BRD&SRS — это документ, объединяющий основные аспекты разработки. Включает описание целей проекта, его историю, потребности и ценности, заинтересованных стейкхолдеров, границы проекта и ограничения, функциональные и нефункциональные требования, а также ключевые вопросы и проблемы.
Шаблон и руководство по заполнению BRD&SRS
1. MAIN GOAL.
Здесь нам необходимо описать назначение продукта/разработки.
2. Предыстория и краткое изложение сути проекта.
3. Формулировка потребностей и ценность проекта/BACCM Canvas.
В этом разделе мы фиксируем потребности, что удовлетворяются с помощью разработки и ценности, которые принесет данная разработка. Эффективно использовать в сочетании с BACCM Canvas.
4. Цель проекта по SMART
Хорошо сформулированная цель позволит определить направление работы и установить конкретные критерии для оценки успеха.
5. Стейкхолдеры продукта
Указываем внутренних и внешних участников проекта. Хорошей практикой является создание матрицы стейкхолдеров или сделать анализ стейкхолдеров с помощью mindmap.
6. Границы проекта и ограничения
Определяем границы разработки, ответственность команды (за какие этапы разработки ПО отвечает команда) и ограничения, включая бизнес-правила и регуляторные требования. Будет гораздо легче проанализировать требования и ограничения от регуляторов, если в предыдущем пункте мы сделали mindmap стейкхолдеров.
7. Функциональные требования и фичи
В данном разделе описываем функционал разрабатываемого продукта. Я предпочитаю описывать их в формате user story с указанием роли пользователя в системе: «Как покупатель, я хочу иметь возможность заказать товар в пункт выдачи», «Как администратор пункта выдачи я хочу иметь возможность отсканировать QR пользователя для получения подробной информации о его товарах»
Данный подход хорошо сочетается с матрицей прав, в которой мы явно укажем, какие пользователи у нас есть и какие у них права для работы с системой. Но можно описать ФТ в формате USE CASE. Также можно зафиксировать диаграмму прецедентов, чтобы не забыть или не потерять часть функционала разработки.
8. Требования к интерфейсу
Указываем требования к дизайну и пользовательскому интерфейсу. Указываем мастхев UI элементы и взаимодействие с ними.
ТЗ дизайнеру описывается следующим образом. Мы передаем ему список ФТ и отражаем способ взаимодействия пользователя с данными фичами. Например, мы передаем список ФТ для регистрации и элементы дизайна. Для процесса регистрации это будут input поля и формы ввода данных, а также кнопка подтверждения регистрации.
9. Нефункциональные требования
Это свойства, которыми должна обладать система. Приведу примеры основных видов требований.
Безопасность. Фиксируем использование защитных протоколов и подходов. Обычно у безопасников есть требования к ПО.
Способность архитектуры к масштабированию. Указываем, должна ли архитектура быть способна к масштабированию или это конечное решение. Указываем данное требование в случаях, если хотим выпустить потенциально классную фичу, которую будем дорабатывать и развивать.
Поддерживаемые устройства и ОС.
Поддерживаемые протоколы и технологии.
Производительность. Поддержка оптимального уровня производительности. Это может заполнить архитектор или разработчик.
— RPS. Запросы в секунду: кол-во запросов в день/кол-во секунд в день.
— Пропускная способность: узнаём размер JSON запросов и ответов (берём данные из контракта API) и умножаем на RPS. Пример: (запрос 200 байт + ответ 200 байт) * rps = кбайт/сек.
— Отношение записи к чтению: считаем кол-во чтений и записей в базе данных для выполнения одного полного сценария использования и делим кол-во операций чтения на операции записи.
— Размер хранилища: умножаем сложенные элементы записи на предполагаемое кол-во операций за год.Языки и локализация. Указываем, какие языки должно поддерживать ПО.
Сохранение и продолжительность хранения данных. Например, требования хранить данные о пользователях 5 лет.
SLI. Уровень доступности. SLI — оценка работы сервиса в данный момент. SLO — договор о поддержании уровня доступности, цель которой необходимо придерживаться. SLA — уровень доступности, за нарушение которой наступают последствия, санкции.
Версионирование ПО. Ведение учёта версий и поддерживаемого этими версиями функционала. Например, данная фича должна работать на ПО версии не ниже 1.3.
НФТ можно также указывать в виде user story.
Как пользователь, я хочу, чтобы сервис был доступен 99,9% времени с 10 до 20 каждый день.
10. Матрица прав
В матрице прав указываем, какие виды пользователей есть в системе, и какие права/возможности взаимодействия с системой им стоит выдать.
11. Вопросы и проблемные моменты
Указываем нюансы, которые необходимо учесть при разработке или раскатке ПО в прод.
Пример заполнения BRD&SRS
1. MAIN GOAL
Необходимо разработать функционал оформления экспресс-доставки в приложении маркетплейса.
2. Предыстория и краткое изложение сути проекта
В данный момент наш маркетплейс не имеет функционала для оформления экспресс-доставки товаров. Поэтому необходимо разработать функционал, позволяющий покупателю оформить заказ и получить его в тот же день.
<Подробное описание фичи и предыстория>…
3. Формулировка потребностей и ценность проекта/BACCM Canvas
4. Цель проекта по SMART
В течение трёх месяцев разработать и внедрить функционал экспресс-доставки для маркетплейса, завершив все этапы разработки, включая проектирование, разработку, тестирование и запуск в продакшен.
5. Стейкхолдеры продукта
6. Границы проекта и ограничения
Технические границы:
Сопровождение разработки командой, ответственной за фичу, на всех этапах жизненного цикла ПО, включая поддержку и развитие ПО.
Функциональные границы:
— Разработка и документирование разрабатываемого функционала.
— Интеграция с различными системами и платформами, необходимыми для обеспечения требуемого функционала.
Организационные границы:
— Разработка проекта в определенные сроки и с установленным бюджетом.
— Соблюдение законодательства и требований в области доставки и защиты персональных данных.
7. Функциональные требования
Процесс оформления заказа:
Как клиент, я хочу иметь возможность заказать товары с доставкой в тот же день.
Управление товарами и выбором типов доставки:
Как продавец маркетплейса я хочу иметь возможность добавить экспресс-доставку для моих товаров.
...
Функционал службы поддержки:
Как сотрудник службы поддержки я хочу иметь возможность видеть тип доставки для заказа.
...
8. Требования к интерфейсу
— Необходимо учесть все функциональные требования.
— Для выбора типа доставки необходимо использовать чекбокс.
— Для отображения подробной информации/онбординга о том, как работает экспресс-доставка, необходимо использовать кнопку, при нажатии на которую всплывает bottom sheet.
9. Нефункциональные требования
Архитектура должна быть масштабируемой. Данная фича будет активно развиваться и будет большое количество различных доработок и интеграций.
Производительность. Поддержка оптимального уровня производительности.
RPS. Запросы в секунду: предполагается, что будет 50 000 активных пользователей в день, для совершения заказа в среднем потребуется 5 запросов. Соответственно, сервис должен выдерживать 50 000*5/24/60/60 = 3 запроса в секунду.
Пиковая нагрузка: предполагается, что ежедневная пиковая нагрузка будет 20 000 в течение одного часа. Соответственно, система должна выдержать пиковую нагрузку в 20 000*5/60/60 = 27 запросов в секунду.
Пропускная способность: запрос, в среднем, весит 200 байт, а ответ 500 байт, соответственно, система должна обеспечивать пропускную способность в (200+500)*3 = 2100 байт в секунду в обычном режиме и (200+500)*27 = 18 900 байт в секунду в пиковой нагрузке.
Отношение записи к чтению: для одного флоу, в среднем, мы делаем 5 запросов: 4 GET-запроса, а оставшийся — POST-запрос. Соответственно, чтение данных будет в 4 запросах, а запись в 1. Отношение записи к чтению — 1/4.
Размер хранилища: умножаем сложенные элементы записи на предполагаемое кол-во операций за 5 лет . Для одной операции необходимо 200 байт памяти в хранилище, а таких операций предполагается 1 000 000 в течение первого года. Соответственно, необходимо выделить не меньше 190 мб.
10. Матрица прав
Роль | Просмотр дашбордов | Изменение дашборда | Добавление устройств | Создание дашборда | Удаление устройств |
|---|---|---|---|---|---|
Администратор | Да/Нет | Да/Нет | Да/Нет | Да/Нет | Да/Нет |
Инженер | Да/Нет | Да/Нет | Да/Нет | Да/Нет | Да/Нет |
Пользователь | Да/Нет | Да/Нет | Да/Нет | Да/Нет | Да/Нет |
Тех. поддержка | Да/Нет | Да/Нет | Да/Нет | Да/Нет | Да/Нет |
11. Вопросы и проблемные моменты
Необходимо согласовать требования для ПО сотрудников склада и курьеров, чтобы не возникало конфликтов при работе.
Бизнес-логика. Спецификация бэкенда
Шаблон и руководство заполнение спецификации бэкенда
1. Логика работы системы
В этом разделе мы детально разбираем, как работает система: от обработки пользовательских запросов до взаимодействия внутренних компонентов. Для наглядности используем:
Диаграммы последовательности: показывают шаги обработки запросов к API (эндпойнтам) и кейсов использования, включая вызовы API, работу с БД и другие операции.
Диаграммы активности: иллюстрируют флоу пользователя, условия, ветвления и взаимодействие компонентов в рамках кейсов использования. Позволяет отобразить путь пользователя от начала и до конца.
Диаграмма компонентов. Хоть это не совсем относится к логике работы, но небольшая карта сервисов, участвующих в разработке, иногда может помочь в поиске оптимальных решений. С помощью данной диаграммы указываем компоненты системы, а также их интерфейсы взаимодействия.
2. Модель данных
В этом разделе фиксируем ER-диаграмма(ы), визуализирующие разрабатываемые сущности предметной области и связи между ними.
3. API. Описание контракта
Описать API (набор методов) можно разными способами: с помощью специальных инструментов (Swagger, API Blueprint) или самостоятельно. Самое главное, чтобы ваше описание API отражало следующие свойства:
Описание запроса. Мы должны подробно указать назначение данного метода. Потомки скажут нам спасибо.
Тип HTTP метода.
URL.
Обязательные headers (заголовки).
Входные параметры. Это path, query и body параметры запроса.
Параметры ответа.
Примеры запроса и ответа.
Можно использовать такой формат описания API:
[HTTP-метод] [URL]
Описание: [Краткое описание функционала]
Headers/Заголовки:
Название | Описание | Обязательность |
Параметры запроса:
Query и path параметры:
Название | Тип | Обязательный | Описание |
… |
Body параметры:
Название | Тип | Обязательный | Описание |
… |
Параметры ответа:
Название | Тип | Обязательный | Описание |
… |
Примеры запроса и ответа:
Пример запроса.
[cURL запроса]✅Успешный ответ 200 ok.
[Пример ответа в формате JSON]❌Неуспешный ответ 400 bad request.
[Пример ответа в формате JSON]4. Корнер кейсы для тестирования бэка
Указываем, какие кейсы могут возникнуть, которые необходимо предусмотреть заранее. Ошибка на этапе проектирования системы стоит дороже, чем на этапе разработки. Так сказать, облегчаем работу нам из будущего :)
Пример заполнения спецификации бэкенда
1. Логика работы системы
Диаграмма последовательности.
Описание взаимодействия систем для эндпоинта POST /api/v1/express-orders.
Диаграмма активности
Легенда:
Серый цвет — действие пользователя.
Зеленый цвет — UI действие.
Синий цвет — сетевое взаимодействие.
Диаграмма компонентов
POST /api/v1/express-orders.
Описание: Создание экспресс-заказа.
Заголовки:
Название | Описание | Обязательность |
app_version | Версия приложения | + |
authorization | Хедер JWT авторизации | + |
Параметры запросы:
Body параметры.
Название | Тип | Обязательность | Описание |
delivery_address | string | да | Адрес доставки |
products | array of integer | да | Массив идентификаторов товаров в заказе |
payment_method_id | integer | да | Идентификатор способа оплаты |
comment | string | нет | Комментарий к заказу (например, пожелания по времени доставки) |
Параметры ответа:
Название | Тип | Обязательность | Описание |
order_id | integer | да | Id заказа |
status | string (enum) | да | Массив идентификаторов товаров в заказе |
Пример запроса:
POST /api/v1/express-orders HTTP/1.1
Authorization: Bearer [ваш токен доступа]
Content-Type: application/json
{
"delivery_address": "ул. Пушкина, д. 1, кв. 1",
"products": [1, 2, 3],
"payment_method_id": 2,
"comment": "Пожалуйста, доставьте до 18:00"
}Пример ответа:
✅Успешный ответ 201 ok.
{
"id": 123, // ID созданного заказа
"status": "created"
}❌Неуспешный ответ 400 bad request.
{
"error": "Неверный формат запроса.",
"details": {
"products":
"Пожалуйста, укажите хотя бы один товар."
}
}4. Корнер кейсы для тестирования бэка
Необходимо предусмотреть, что будет, если попытаться создать экспресс-доставку товара, для которого экспресс-доставка не предназначена.
Необходимо предусмотреть, что будет, если отправить два одинаковых запроса, сработает ли проверка на ключ идемпотентности.
UI-логика. Документация фронтэнда
Шаблон и руководство заполнение фронт доки
1. Навигация по экранам
В этом разделе представлена последовательность вызовов экранов и UI-элементов. Для визуализации используется диаграмма активности, отображающая только действия пользователя и UI-активности.
2. UI логика экранов
В данном разделе указываем экраны и свойства UI-элементов для них. Можно использовать такой шаблон для описания поведения UI-элементов, находящихся на экране. В последнее время я стал гораздо реже пользоваться данным разделом. В основном описываю лишь некоторые UI-элементы.
Элемент | Условия показа | Описание | Действие | Конфигурирование |
Название/тип элемента | Условия, для отображения элемента | Описание элемента | Что данный элемент делает | Может ли данный элемент настраиваться, конфигурироваться |
3. Локализация
Данный раздел актуален, если нам необходимо разработать ПО, умеющее работать на нескольких языках. Можно использовать следующий шаблон:
Ключ | Русская локализация | Английская локализация |
Также в целом советую хранить тексты и подобные ресурсы не в коде, а в отдельном месте, например, в конфиге. Так мы сможем изменить текстовку продукта меньшими усилиями, не привлекая разработчиков.
Пример заполнения фронт доки
1. Навигация по экранам
2. UI логика экранов
Элемент | Условия показа | Описание | Действие | Конфигурирование |
Форма регистрации | Пользователь нажал «Зарегистрироваться» | Форма регистрации, которая всплывает при нажатии на кнопку, открывается в центре экрана. Содержит кнопки и текстовые описания | Содержит поля для ввода данных (зависит от конфигурации) и кнопки для отправки формы и отмены регистрации. | Да, конфигурируется наличие и количество методов полей ввода и текста |
3. Локализация
Ключ (название ресурса) | Русская локализация | Английская локализация |
button_continue | Продолжить | Continue |
Продуктовая аналитика
Шаблон и руководство заполнения
1. События
События — это «кирпичики» для построения и расчёта метрик. Можно использовать такой шаблон для описания событий.
Тип события | Название события | Триггер | Параметры (атрибуты) события | Описание параметра | Примеры значений |
2. Метрики
Необходимо указать, какие метрики мы собираем и как их считаем. Также необходимо добавить воронку продаж в рамках разрабатываемого продукта (если данная воронка есть).
Этапы воронки (стадия флоу пользователя):
1 этап | 2 этап | 3 этап | 4 этап | .... |
Продуктовые метрики:
№ | Название | Что измеряем | Как измеряем |
Технические метрики:
№ | Название | Что измеряем | Как измеряем |
3. Логирование
Хорошей практикой является проектирование логов для разборов инцидентов заранее. Можно использовать данный шаблон для указания параметров логов:
Условие отправки лога | Уровень логирования | Параметры | Значение |
Пример заполнения
1. События
Тип события | Название события | Триггер | Параметры (атрибуты) события | Описание параметра | Примеры значений |
Нажатие кнопки | Выбрать тип доставки | Выбор типа доставки | 1. user_id 2. delivery_type | 1. id пользователя 2. Тип доставки | 1. 1231234 2. express |
2. Метрики
Этапы воронки.
1 этап | 2 этап | 3 этап | 4 этап | ... |
1 экран | 2 экран | 2 экран. Выбор условий | 3 экран | ... |
Продуктовые метрики.
№ | Название | Что измеряем | Как измеряем |
1 | Общее количество заказов в месяц | Измеряет количество оформленных пользователями заказов за один календарный месяц | Считаем по количеству заказов добавленных в БД |
2 | Количество успешных доставок | Измеряет количество успешно выполненных доставок за один календарный месяц. Необходима для общей оценки работы сервиса/приложения | Считаем по количеству заказов со статусом «Доставлено» |
Технические метрики.
№ | Название | Что измеряем | Как измеряем |
1 | Время отклика | Время, которое требуется системе для ответа на запрос пользователя | Засекаем время с момента получения запроса до момента получения ответа. Включаем в это время обработку запроса, вычисления, передачу данных и другие операции, необходимые для генерации ответа |
2 | Уровень доступности | Способность системы оставаться доступной и функциональной для пользователей в течение определенного времени | Измеряем процент времени, в течение которого система остается доступной для пользователей без сбоев или проблем. Можем использовать мониторинг сервисов или инструменты для отслеживания времени простоя и вычисления общего процента доступности |
3. Логирование
Условие отправки лога | Параметр | Значение |
Отправить запрос на создание заказа | message | Тело запроса |
level | INFO | |
userid | Id пользователя | |
... | ... | ... |
Если вы хотите скопировать данный шаблон себе в Notion или ознакомиться с ним в более удобном формате, я оставил ссылку на него в закрепленном сообщении в моем телеграмм-канале, где я рассказываю про работу аналитика, собеседования и карьеру в IT.
