Коллеги скинули всё ещё актуальную заметку про предварительный анализ. Не обращайте внимания на название, суть там в другом — перед тем как что-то реализовывать, это стоит описать в доке.
Например:
— какие изменения нужно внести
— какие будут контракты
— как лучше тестировать
— etc
Я сам исповедую примерно такой подход уже в нескольких конторах. Кажется, что это бюрократия и трата времени, но в итоге у всех участников выравнивается понимание конечного результата. Особенно когда такая дока пишется сообща. Тестеры понимают, как тестить, разрабы понимают, как ревьювить и т.д. Метод сильно отличается от классического «вот вам задача в жыре, сами понимайте, что я тут имел ввиду, вы ж умные»
В итоге количество непоняток и переделок снижается в разы, легко организовать трассировку, а разработчики уходят с полным пониманием задачи и повышается точность прогнозирования сроков
Что ещё можно добавить в такую доку?
— контекст: зачем мы вообще это делаем, какую задачу решаем
— модель предметной области на основе Event Storming
— use case и альтернативные сценарии
— макеты в Фигме
— какая документация должна родиться
— какие метрики нужно вывести
— какие алерты настроить
— что поменяется в инфраструктуре
— риски безопасности
— любые другие технические подробности
— ссылки на другие документы
Несколько важных наблюдений
1. Документ обычно описывает ближайшую задачу, никаких «на вырост». Версии тут как таковых нет, потому что мы очень плохо можем в дифф.
2. Документ обычно пишется на пользовательскую историю или похожий артефакт, то есть в изготовлении доки задействуются и фронтендеры и бекендеры и тестировщики, которым это потом чинить. Далее сторя разбивается на подзадачи для конкретных спецов. Фактически мы начинаем разрабатывать на бумаге, продумываем самые сложные сценарии, а кодить можно уже спинным мозгом. В этом отличие от классических требований (даже самых подробных) описываемых аналитиками.
3. Документирование может отмереть, если команда нарастит квалификацию и достаточно сработается. Это нормально, потому что цель — не бумажка, а общее понимание результата.
4. Подход слабо работает в лапшекоде уровня «после просмотра промыть глазаа хлоргексидином», ибо количество непредвиденных ситуаций ломает начальную идею полностью. Хотя полностью от них избавиться не получится даже в поддерживаемом коде