Аналитический долг в документации (и иных аналитических артефактах)

Документация бывает актуальней, чем разработанная система, если выставляет к ней новые требования, но чаще она менее актуальна, поскольку в неё не внесены те детали, которые вызваны столкновением разработки с реальностью в виде применяемых инструментов, технических ограничений оборудования и внешних систем.

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

Поэтому любая документация развивающихся систем неизбежно содержит в себе или аналитический долг (там, где аналитика не поспевает за разработкой), или аналитический заказ (там, где аналитика выставила новые требования разработке), и это «или» не исключающее, а дополняющее.

В общем случае это не проблема, если есть система работы с аналитическим долгом и время на его погашение. Как и в случае с техдолгом, постепенный и постоянный рефакторинг документации позволяет уменьшить аналитический долг, и приблизить текст к реальности.

Насколько важно полное соответствие

Идеал не нужен и за него никто никогда не заплатит. Документация, которая на 80% соответствует коду, но содержит все ключевые бизнес-правила и принятые архитектурные решения, будет ценнее, чем документация, на 100% соответствующая коду, но погрязшая в деталях. Необходимо понимать, что есть некая критическая актуальность документации, выход за пределы которой нецелесообразен. Прежде всего актуальными должны быть описания интерфейсов API, схем ключевых бизнес-процессов, core-домена. Остальное можно обновлять по требованию, и это не будет считаться „долгом“, а будет осознанной стратегией.

Что делать для рефакторинга

Находить и переписывать расплывчатые формулировки на точные алгоритмы; актуализировать скриншоты и схемы; если что-то можно исправить за пять минут — исправлять сразу; оставлять комментарии к неясным элементам схем и спецификаций с вопросами; обрабатывать накопившиеся вопросы (свои и чужие) по мере возвращения к текстам и схемам: менять документацию там, где комментарий уместен; аргументированно отвергать неуместные комментарии; объединять в логические блоки те комментарии, которые требуют более глубокой проработки.

Кто и когда это должен делать

За свою документацию отвечает каждый аналитик. Нужно согласовать с руководством и запланировать время на рефакторинг в общем объёме основных задач, браться за него в те дни, когда аналитическая проработка новой функциональности буксует на месте, либо по требованию разработки, тестирования или службы технической поддержки. Читать документацию и оставлять комментарии должны разработка, тестирование, служба поддержки и product owner.

И главные помехи на пути — это избыточность и неясность. Путанные, противоречивые, многословные описания хуже, чем ясные, однозначные и краткие, содержащие необходимый и достаточный набор слов (картинок, иных символов), и путь от первого состояния ко второму — тоже аналитический долг.

Поэтому читать свою документацию лучше в режиме редактирования (чужую — в режиме комментирования), и сразу отмечать, уточнять и исправлять неясности, сокращать избыточные описания и распутывать спагетти в BPMN и UML-схемах.

Итеративное улучшение — единственный способ держать долг под контролем. Не идеал, но работающий процесс.