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

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

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

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

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

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

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

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

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

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

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

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

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

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

Внутренняя документация — это договор между разработкой и менеджментом о том, что необходимо выполнить и в каком виде.
Прочие функции на самом деле вторичны: хранение истории изменений требований к системам, история поиска решений, история возражений и зафиксированных ограничений и всё прочее лишь дополняет первую и самую важную часть.
Документация создаёт определённость для разработки и для менеджмента, фиксируя наполнение работ хотя бы на ближайший спринт.

Не очень важно, продуктовая или проектная деятельность у компании.

Важно именно закрепление ожиданий.

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

Ровно как работу бэкенда часто можно свести к перекладыванию JSON в записи в БД, а записи в БД в XML; или работу фронтенда можно привести к правилам формирования JSON из данных, введённых пользователем в форме (или отображения данных, полученных в JSON от бэка в интерфейсе), работу системного аналитика можно свести к правилам перекладывания JSON’ок.

Но делать это не нужно. Аналитик фиксирует социальный контракт в рамках конкретного проекта или продукта на конкретный временной промежуток.