Почему разработчики задают вопросы…

Я все чаще замечаю одну и ту же проблему в проектной документации.

Аналитик подробно описывает, что должна делать система, но сознательно избегает описания взаимодействия ее компонентов.

Обычно это объясняют просто: «Это уже техническая реализация».

На первый взгляд логично. Но на практике именно здесь и появляется большинство вопросов со стороны разработки.

Например, в требованиях написано: «При открытии карточки клиента заполнить поля данными сущности <Клиент> и в лучшем случае описание маппинга полей экрана с полями сущности.»

Все понятно... пока задача не попадает разработчику.

Сразу возникают вопросы. Откуда взять данные? Какой сервис является источником? Когда выполнять запрос? Что делать, если сервис недоступен? Как обработать ошибку? Нужно ли преобразовывать ответ перед отображением?

Получается парадокс. Документ, который должен уменьшать неопределенность, наоборот, переносит ее в обсуждения команды.

На мой взгляд, причина в том, что часто путают реализацию и контракт взаимодействия.

Реализация — это SQL-запросы, классы, паттерны, внутренняя логика сервисов. Это действительно зона ответственности разработчиков.

Но описание того, как компоненты системы взаимодействуют друг с другом, — это уже часть требований.

Например, требование может выглядеть так:

«При открытии экрана вызвать метод GET /api/clients/{clientId}, где clientId — идентификатор клиента, переданный при открытии карточки.

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

Если метод вернул ошибку, отобразить пользователю уведомление с текстом из параметра message.»

Заметьте, здесь нет ни слова о языке программирования, ORM или внутреннем устройстве сервиса. Но разработчик уже понимает, какие компоненты должны взаимодействовать, какие сценарии необходимо реализовать и какое поведение ожидает бизнес.

Такая документация дает еще один важный эффект: она становится единым источником понимания для всей команды. Разработчик реализует задачу, тестировщик строит тест-кейсы, а архитектор оценивает влияние на систему, не тратя время на десятки уточняющих вопросов.

Я не утверждаю, что каждое требование должно содержать описание всех API. Но если взаимодействие между компонентами влияет на поведение системы, оно должно быть явно зафиксировано. Иначе команда будет каждый раз проектировать это заново уже в процессе разработки.

Для меня есть простой критерий качества документации: если после прочтения разработчик вынужден идти к аналитику с десятком уточняющих вопросов, значит документ еще не закончен.

Хорошая документация не просто описывает, что должна делать система. Она снимает неопределенность настолько, чтобы вся команда одинаково понимала будущую функциональность.

А как вы оцениваете качество аналитики? Достаточно ли описать бизнес-логику или хороший документ должен позволять разработчику приступить к реализации практически без дополнительных вопросов? Где, на ваш взгляд, проходит эта граница? Именно тогда документация начинает экономить время, а не отнимать его.

Почему разработчики задают вопросы… | Сетка — социальная сеть от hh.ru