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

Я знаю ровно один способ этого избежать — договариваться на том языке, на котором не может быть двух толкований. Конкретно в случае договоренностей между бекендом и фронтендом — на языке API. Когда бекендер говорит, что реализует какие-то методы, у него в голове не сработает и половина триггеров из тех, которые щёлкнут, когда он увидит конкретные поля в конкретных объектах апишки. Когда фронтендер говорит, что согласен на какую-то реализацию со стороны бекенда, он скорее всего не может быстро оценить сколько и каких вызовов ему придётся сделать, чтобы собрать всю страницу целиком. А когда он увидит API он может сразу сказать каких методов ему не хватает, чтобы не плодить лишние запросы.

Проблема только в том, что API не всегда достаточно, чтобы подробно описать реализацию сложной функциональности. Обычно нужна ещё какая-то схема взаимодействия, объясняющая, что за чем идёт, какая вариативность присутствует, из какого состояния в какое мы можем попасть и т.д. Найти универсальный инструмент, помогающий ответить на этот вопрос, у меня пока не получилось. Каждый раз это муки выбора, много попыток нарисовать что-то понятное в Miro, а потом ещё и много неудобного редактирования, когда договоренности меняются. Поэтому у меня вопрос — а как вы документируете такого рода договоренности, чтобы это было наглядно и не слишком трудозатратно?