Мотивация - ключевой момент

У меня есть опытный разработчик, самый большой его плюс в том, что он работает "от документации". Т.е. пока в документации задача не записана, он не обновляет код. В случае API, пока я не обновлю Open API спеку и не обновлю техреение, он не будет обновлять код.

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

Новая доработка? Давайте задачу + спеку + апи, если есть. Только после этого в работу. Если что-то пошло не так в процессе, то спека/апи дообновляются.

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

Он понаделает костылей и велосипедов, а моей задачей становится приёмка на стороне тестирования - чтобы всё работало как надо.

Т.к. описывай или нет - всё равно сделает по-своему.

Скорее это история про легаси, причем легаси скорее не технологическое а из прикладного домена. Есть много регуляторики и разных правил уровня бизнес-логики, которые должны быть документируемы и управляемы.

В моём случае это не только легаси, но и сложный процесс на стороне отдела и его правила обработки документов.

Т.е. сама обработка + складывание документов в легаси систему.

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

Вот я тоже не понимаю

Это вы ещё VP of Engineering не вспомнили 😂

Архитектурный шпагат

А можете поподробнее рассказать об устоявшихся форматах документации помимо Open API? Что ваши разработчики понимают?

++. Иначе никак. Нужна правая рука (или две), желательно с головой.

Может быть я что-то упустил.

Вы действительно считаете, что кто-то способен разрабатывать полезную документацию кроме исполнителей (владельцев знаний)?

Автоматическую генерацию и реверс инжиниринг (As Is) мы в расчёт не берём.

Допустим это так. Давайте тогда требования к квалификации таких людей составим.

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

При этом, что странно, бутылочное горлышко - люди, а не деньги

Я считаю что Архитектору необходимо писать доку, при принятии решения им. Так же содержание проекта —низкоуровневые решения делегируются разработке, где они пишут документацию. Аналитик остается только в формате сбора и относительной формализации требований (очерчивает состав) и в зависимости от уровня PM может быть управления требованиями (хотя изменение состава это PM). Аналитик так сказать становится владельцем продукта наверное.

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