Иначе RE:RE:RE:RE:RE:RE:RE:RE:RE:RE:RE:ПЗ.docx от Коли Иванова
и RE:RE:RE:RE:RE:RE:RE:RE:RE:RE:RE:ПЗ.docx от Маши Старцевой
И это только в рамках проекта компании.
С заказчиками всё еще хуже )

Руководство не выделит ресурсов, если не показать ценность для бизнеса

Все вот эти value co-creation

Если из-за кривой документации регулярно появляются при-1 баги, тогда это доказать легко

В принципе, и на knowledge rediscovery затраты человеко-часов можно посчитать, переведя в деньги

Извините, я, наверное, самоочевидные вещи пишу здесь

Нее, очень хорошие вещи.

И эту картинку точно не все видели, например я не видел. В общем, пиши ещё.

Спасибо! Возвращаясь к теме - для документирования апи мы очень успешно применяли сваггер, который вставлялся в страницу в Confluence. Генерация сваггера и деплой в конфлюэнс были шагами билд пайплайна после тестов

Затраты - только на первоначальную настройку и научить девелоперов писать xml-комментарии сразу в коде

Потом это zero-maintenance решение

А чтобы не забывали - линтер, который не пропускает билд, если нет комментариев

Вот ты внедрил этот новый инструмент. Теперь у тебя есть все эти удобства. Как это повлияет на создание результата? Увеличит ли качество документации, скорость её создания? Привнесёт ли какую-то ценность заказчикам?

А как линтер понимает, насколько комментарий полезен?

Линтер формально подходит к этому вопросу.

Есть/нет, длина и примерное соответствие шаблону

Насколько полезны комментарии, оценивает ревьюер пулл-реквеста

Да нет, не очевидные. Сколько копьев поломано, когда специалист видит ценность в технологии, но его никто не слышит. Между прочим одна из причин проф. выгорания.

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

Это как питчи у стартаперов - они придумали штуку и теперь обосновывают, почему нужно инвесторам нужно вложить денег.

А в компании нужно обосновать почему руководству нужно вложить денег в технологию.

Я последние пару лет со стороны лида/менеджера смотрю на эти вещи. Поэтому частенько приходится уговаривать инженеров не внедрять ту или иную новую блестящую штуку, если она не вписывается в стратегию

В том числе и по части документации