Тимлид задрал требовать писать доку на каждый чих. Проект пишется на коленке, требования меняются раз в неделю.
Я считаю, что лучший код - самодокументируемый. Пока я потрачу три часа на описание АПИ, дизайн уже переделают. Нужно ли писать документацию в таких условиях или это просто трата девелоперского ресурса ради галочки?
Была такая же позиция пока не ушел один ключевой разраб. Он тоже верил в самодокументируемый код.
В итоге мы три недели расковыривали его велосипеды чтобы просто понять почему на определенном юзкейсе падает платежка. Теперь пишем доку всегда. Пусть даже минимальный README, но он должен быть.
Код твой говно через месяц сам не вспомнишь что там за логика была. Пиши хотя бы кратко схемы в маркдауне. Про самодокументируемый код обычно рассказывают ленивые джуны.
Писать надо только то что реально болит. Описывать каждый метод - глупость. Опишите глобальную архитектуру, как данные ходят, и контракт АПИ. Все остальное сгенерит swagger.
swagger + ts типы. Ручная дока в ворде или ноушене умирает в день написания.
а почему нельзя просто писать комментарии к сложным местам в самом коде... зачем раздувать сущности. если код часто меняется то и дока будет постоянно врать
