Среди руководителей разработки, внедряющих agile, считается, что гибкие методологии противоречат документации. Что документация - зло, она тормозит процессы и максимум того, что может производить команда - это пользовательская документация. Они возмущаются, что "Работающий продукт важнее исчерпывающей документации" и каким-то образом делают вывод, что внутренней документации в agile не должно быть. Это полная чушь!
Если вы упираете на формулировки в Agile-манифесте и слова авторитетных людей - обратите внимание на Constraints (http://agilemodeling.com/artifacts/constraint.htm)
Разработчики не хотят писать документацию - они любят писать код. Они не умеют и не хотят осваивать русский язык, с его сложными оборотами и неоднозначными формулировками. Однако именно разработчики и инженеры являются носителями знания о продукте. Если на крупном проекте не будет хорошей внутренней документации, то вы обрекаете себя на более трудную отладку багов, на чудовищный bus factor и полную непрогнозируемость работ.
Когда компания приходит к мысли о внутренней документации - пишется она в последний момент, уже после того, как всё сделано. Командой инженеров эта задача воспринимается как "дополнительная", "не нужная" - ведь продукт-то уже работает. И инженеры ищут какое-то изящное техническое решение проблемы, например автогенераторы.
Однако автогератор - это лишь преобразователь, если на вход ему подать "плохую" информацию - на выходе она лучше не станет. В результате документация отторгается и забывается, а проблемы, связанные с её отсутствием считаются "нерешаемыми", либо подпираются костылями.
Я считаю, что решение ребуса существует.
Прежде всего - стоит определиться, что документация - это зафиксированные коммуникации между разными ролями в коллективе. Важно два слова: зафиксированные и коммуникации, оба они открывают море вариантов.
Не обязательно документация - это выверенные тексты, но обязательно - это структурированная и, что гораздо более важно, обновляемая информация. Обновляемость документации - это ключевая метрика.
