Работаю в одном крупном банке из ТОП-10. У нас внедрили доку в коде. Большинство адекватных аналитиков это тихо ненавидят. Помимо того что этой документацией по итогу никто не пользуется, так еще и это содержит описание только микросервисов, а все остальное все равно нужно описывать в конфе. Затраты на доку в коде больше в 2-3 раза. Все кто пробовал сразу туда писать, сталкивались с проблемами. А просмотреть чужие доки из чужих репозиториев нельзя. Не мудрено, что у нас увеличилась текучка кадров, снизилась удовлетворенность. А разрабы как смотрели в конфу, так и смотрят. В общем если вы еще думаете внедрять или нет, то однозначно НЕТ! Лучше старый добрый автоматический сваггер и дока в конфе.
По моему опыту документация рядом с кодом очень удобна для описания микросервисов, но далеко не всю документацию удобно так вести. Это связано с тем что некоторую документацию потом просто будет не найти в коде. Так что лучше конечно комбинировать Confluence и доку в коде, тогда на проекте будут извлечены преимущества обоих подходов.
Гораздо выгоднее было сразу решать как множество мелких задач/изменений. Самый главный вывод так и не прозвучал.
P.S. Более того, чем меньше инкремент, тем быстрее получишь обратную связь от конечного пользователя. Понимаю, что в случае разработки MVP это не всегда применимо.
В статье нет нормального ответа на вопрос «зачем». Можно уточнить пожалуйста более подробно.
Вижу исключительно хвалебные отзывы о doc as code -> Статью написала Технический писатель -> Больше вопросов к однобокости статьи нет
Работаю в одном крупном банке из ТОП-10. У нас внедрили доку в коде. Большинство адекватных аналитиков это тихо ненавидят. Помимо того что этой документацией по итогу никто не пользуется, так еще и это содержит описание только микросервисов, а все остальное все равно нужно описывать в конфе. Затраты на доку в коде больше в 2-3 раза. Все кто пробовал сразу туда писать, сталкивались с проблемами. А просмотреть чужие доки из чужих репозиториев нельзя. Не мудрено, что у нас увеличилась текучка кадров, снизилась удовлетворенность. А разрабы как смотрели в конфу, так и смотрят. В общем если вы еще думаете внедрять или нет, то однозначно НЕТ! Лучше старый добрый автоматический сваггер и дока в конфе.
По моему опыту документация рядом с кодом очень удобна для описания микросервисов, но далеко не всю документацию удобно так вести. Это связано с тем что некоторую документацию потом просто будет не найти в коде. Так что лучше конечно комбинировать Confluence и доку в коде, тогда на проекте будут извлечены преимущества обоих подходов.
Согласен. Мягкие навыки сильно сложнее прокачивать, поэтому они должны уже быть у аналитика.
Гораздо выгоднее было сразу решать как множество мелких задач/изменений. Самый главный вывод так и не прозвучал.
P.S. Более того, чем меньше инкремент, тем быстрее получишь обратную связь от конечного пользователя. Понимаю, что в случае разработки MVP это не всегда применимо.