Как писать требования и документацию к проекту. Полный гайд с шаблоном документации и примерами заполнения

[Ruslan964]

крутое, подробное описание!

скинул знакомым для ознакомления

[binary_file]

Благодарю!

[TheMultiFive]

Вполне себе неплохое описание для новичков, но возникает пару вопросов:
1. Зачем описывать контракты API в таблицах, когда уже кучу времени используется openApi спецификация, с возможностью кодогенерации. Представляю лицо разработчика когда он будет переписывать атрибуты body в API с таблицы и их 50+.
2. Откидывать ошибки API на русском языке - интересное, конечно, решение. Но в протоколе HTTP все коды ответа регламентированы и стоит использовать их нейминг. Если вам нужно подкинуть description ошибки - принято писать их на английском языке.

[binary_file]

Привет! Спасибо за коммент

Насчет первого пункта частично согласен, но для новичка будет достаточно сложно сразу писать в openapi, также я указал, что можно это делать в openapi или blueprint форматах. Моя цель из пункта про API - указать главные параметры, которые надо фиксировать. Также в docs as code часто прописывают вручную, не у всех есть частичная генерация доки. Ну и тут еще зависит от подхода, если у нас Api first, то генерация openapi подходит, если же сначала дока, а потом код, то тут уже генерация openapi не подойдет. Но в целом - конечно гораздо лучше сразу использовать openapi, если подходы позволяют

Насчет второго - полностью согласен, решил для наглядности показать на русском языке

[dph]

А зачем новичку, который даже OpenAPI не может освоить, пытаться описывать API? Проработка программных интерфейсов - сложная инженерная работа, без опыта работы хотя бы миддлом на бэке ее делать категорически не стоит (а по хорошему, это вообще должны писать инженеры, а не аналитики).
И OpenAPI - это как раз про документацию, не про код.

[olku]

В чем преимущество по сравнению с Arc42?

[lesha_spb]

Arc42 - это шаблон для описания архитектуры. Здесь же речь о более низком уровне - описании требований.

[dph]

Тут довольно мало про описание требований, разве что про User Story, да и то без мотивационной части (что делает их практически бесполезным).
Описание API - это не требования, это техдизайн. Как и вообще все, что написано в главе "Бизнес-логика".

[tempart]

Спасибо за подробную статью. Как вариант подступиться к задаче, очень даже хорош.

Продуктовая аналитика. 1. События

Более традиционно принято это показывать в виде схемы (бизнес-)процессов на этапе формирования ФТ. Помогает и ФТ точнее формулировать, и, если надо, то показывать логику появления событий, их результат. Метрики - это уже одно из применений схемы, а не причина появления такой схемы.
Читать события в табличке без из визуализации я б не осилил :)

Статья достаточно большая, мне не хватило Содержания. Неудобно искать

[dph]

Ну, лучше вообще перед описанием ФТ провести EventStorming и сделать описание доменных моделей. То, что описано в статье - просто куча бесполезных строчек, никак не связано с описанием требований, увы.

[a3aquB]

Это не совсем Юзер Стори:
Как пользователь, я хочу, чтобы сервис был доступен 99,9% времени с 10 до 20 каждый день.

[HiPF]

Ага, вряд ли пользователю оно прямо в таком виде нужно

Выглядит больше как обычное не функциональное требование

[binary_file]

Это лишь пример оформления НФТ. Я так и указал в гайде

"НФТ можно также указывать в виде user story."

[a3aquB]

Можно, но приведенный пример не является корректным user story

[ValeryGL]

Верно, не всё пользовательская история, что написано по шаблону "я, как А, хочу Б...".

[dph]

Не надо описывать НФТ в виде user story.
Тем более в user story обязательно должна быть мотивационная часть, иначе оно бесполезно. Все указанные в статье user story - таковыми не являются (

[vlaubenshtein]

Не хватает секции "чтобы что" ?

[zhivtone]

Не функционал, а функциональность

[a3aquB]

Мне кажется, со сменой поколений это холивар ушел. Просто приняли. Как приняли, что кофе может быть среднего рода

[ValeryGL]

... как системная аналитика вместо анализа ;)

[HumbleCommentor]

Подушню немного. Слово "функционал" надо заменить на "функциональность".

В остальном более-менее норм. На месте диаграммы компонентов иногда (часто) полезнее отрисовать полноценную C4.

[GDSgr3]

А почему стейкхолдеры дважды упоминаются?

[binary_file]

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

[dph]

Очень много сомнительных практик в этом шаблоне.
Потеряна мотивация (а описание "зачем" - самое важное, что должен описывать аналитик), очень много техдизайна (плохо описанного) вместо требований, в описании НФТ нет вообще ни одного корректного пункта, нет ничего про UX (а задание на UX делается до задания для дизайнеров. Впрочем, задание для дизайна тоже предполагает бриф, про что не сказано ни слова).
Надеюсь, ничего из этого шаблона реально в банке не используется.