#docs
Недавно тут случилось зарамсить по поводу документации. Мой поинт был в том, что чем больший процент документации генерится из кода, тем лучше, ибо эта штука всегда актуальная и бла-бла.
Поинт более опытных коллег заключался в том, что сгенерированные доки конечно актуальные, но чуть менее чем полностью бесполезные. Все, конечно, остались при своем, но вот тут вот внезапно натыкаюсь на пост и прямо вот сложилось.
Раньше я думал, что часть доков надо генерить, а остальное писать(генерим апи доки сваггером, датафлоу и деплоймент схему из dt/service mesh DAG'a и кубера ну и кейсы Cucumber'ом + рисуем руками фичи, и интеграции с 3rdparty)
Щас же пришел инсайт, что надо не генерить ИЛИ рисовать, а генерить И дорисовывать. Т.е. взяв, для примера, схему апи, надо в шапку сваггера руками положить пример хеппифлоу в каком-то виде(сикуенс диаграммы или еще как-то), с человеческим описанием что делает апи и для чего нужно + возможно указать акторов.
Кароч вот такие мысли, котаны. Что думаете?