Comments 24
крутое, подробное описание!
скинул знакомым для ознакомления
Вполне себе неплохое описание для новичков, но возникает пару вопросов:
1. Зачем описывать контракты API в таблицах, когда уже кучу времени используется openApi спецификация, с возможностью кодогенерации. Представляю лицо разработчика когда он будет переписывать атрибуты body в API с таблицы и их 50+.
2. Откидывать ошибки API на русском языке - интересное, конечно, решение. Но в протоколе HTTP все коды ответа регламентированы и стоит использовать их нейминг. Если вам нужно подкинуть description ошибки - принято писать их на английском языке.
Привет! Спасибо за коммент
Насчет первого пункта частично согласен, но для новичка будет достаточно сложно сразу писать в openapi, также я указал, что можно это делать в openapi или blueprint форматах. Моя цель из пункта про API - указать главные параметры, которые надо фиксировать. Также в docs as code часто прописывают вручную, не у всех есть частичная генерация доки. Ну и тут еще зависит от подхода, если у нас Api first, то генерация openapi подходит, если же сначала дока, а потом код, то тут уже генерация openapi не подойдет. Но в целом - конечно гораздо лучше сразу использовать openapi, если подходы позволяют
Насчет второго - полностью согласен, решил для наглядности показать на русском языке
А зачем новичку, который даже OpenAPI не может освоить, пытаться описывать API? Проработка программных интерфейсов - сложная инженерная работа, без опыта работы хотя бы миддлом на бэке ее делать категорически не стоит (а по хорошему, это вообще должны писать инженеры, а не аналитики).
И OpenAPI - это как раз про документацию, не про код.
В чем преимущество по сравнению с Arc42?
Arc42 - это шаблон для описания архитектуры. Здесь же речь о более низком уровне - описании требований.
Спасибо за подробную статью. Как вариант подступиться к задаче, очень даже хорош.
Продуктовая аналитика. 1. События
Более традиционно принято это показывать в виде схемы (бизнес-)процессов на этапе формирования ФТ. Помогает и ФТ точнее формулировать, и, если надо, то показывать логику появления событий, их результат. Метрики - это уже одно из применений схемы, а не причина появления такой схемы.
Читать события в табличке без из визуализации я б не осилил :)
Статья достаточно большая, мне не хватило Содержания. Неудобно искать
Это не совсем Юзер Стори:Как пользователь, я хочу, чтобы сервис был доступен 99,9% времени с 10 до 20 каждый день.
Ага, вряд ли пользователю оно прямо в таком виде нужно
Выглядит больше как обычное не функциональное требование
Это лишь пример оформления НФТ. Я так и указал в гайде
"НФТ можно также указывать в виде user story."
Можно, но приведенный пример не является корректным user story
Не надо описывать НФТ в виде user story.
Тем более в user story обязательно должна быть мотивационная часть, иначе оно бесполезно. Все указанные в статье user story - таковыми не являются (
Не хватает секции "чтобы что" ?
Не функционал, а функциональность
Подушню немного. Слово "функционал" надо заменить на "функциональность".
В остальном более-менее норм. На месте диаграммы компонентов иногда (часто) полезнее отрисовать полноценную C4.
А почему стейкхолдеры дважды упоминаются?
Очень много сомнительных практик в этом шаблоне.
Потеряна мотивация (а описание "зачем" - самое важное, что должен описывать аналитик), очень много техдизайна (плохо описанного) вместо требований, в описании НФТ нет вообще ни одного корректного пункта, нет ничего про UX (а задание на UX делается до задания для дизайнеров. Впрочем, задание для дизайна тоже предполагает бриф, про что не сказано ни слова).
Надеюсь, ничего из этого шаблона реально в банке не используется.
Как писать требования и документацию к проекту. Полный гайд с шаблоном документации и примерами заполнения