Итак, есть большой и сложный проект, в котором я работаю аналитиком. Большая часть его документирована достаточно хорошо, меньшая — довольно плохо, и есть большое число мелких деталей и особенностей, которые не описаны нигде. Для последних в лучшем случае — есть задача в джире формата «сделать так», в худшем — только коммит или текущее состояние базы.

По ряду причин внутренней корпоративной политики функционального заказчика спрашивать нежелательно.

Приходится заниматься аналитической археологией.

Для практической археологии вам необходимы:

1. Подтверждённый высокий приоритет проблемы.
   1. Есть перечень проблем, воспроизводимых тестировщиками вручную и на автотестах, которые, однако, либо не могут быть воспроизведены пользователем, либо будут доступны малому числу пользователей по бизнес-процессу.
      1. При этом эти проблемы могут иметь существенные финансовые и юридические риски в случае наступления, например, инциировать судебные разбирательства. Оценка проблемы по матрице оценки Влияние на пользователя (High/Medium/Low) x Частота использования (High/Medium/Low), проведённая аналитиком, поможет менеджеру поставить правильный приоритет и назначить спринт для исправления проблемы, закрепить соответствующие полномочия у аналитика.
2. Доступ в систему управления задачами.
3. Доступ к тестовому стенду, базе данных и, иногда, коду на нём.
   1. Иногда необходим доступ к реальным данным, то есть нужна возможность выполнить запрос к БД в продуктовой среде через специалиста, имеющего такие права (или самостоятельно).
   2. Иногда необходим доступ (на чтение) в репозиторий и доступ к логам.
4. Необходима возможность получить разработчика-консультанта, для теханализа и объяснения логики работы существующего кода.
5. Поддержка команды разработки для устранения проблемы (предполагается по умолчанию, как обеспеченная тим-лидами и менеджментом в ходе командопостроения).

Как всё выглядит на практике, когда есть время организовать работы правильно:

1. Подготавливается описание состояния системы «Как оно есть сейчас». Довольно редко этим занимается аналитик, гораздо чаще проблему находят тестировщики или приносит служба технической поддержки. Но иногда аналитику приходится посмотреть код самому или попросить посмотреть код тестировщика или разработчика.
   1. Полноценное описание состояния «Как оно есть сейчас» может занять не один день работы аналитика и, иногда, разработчика (в роли технического консультанта по коду и для технического анализа поведения системы). Такие проблемы требуют привлечения внимания менеджеров.
      1. Скорее всего именно на этапе технического анализа (tracer bullet) будет уточнён код на бэкенде и используемые им процедуры БД и таблицы, а так же внешние источники таблиц, в случае если они ETL.
2. Определяется функциональный владелец части системы. Это может быть тим-лид аналитики, тим-лид разработки, архитектор, какой-то отдельный разработчик или его может не быть вовсе (в таком случае функциональный владелец — это аналитик-археолог).
3. Аналитик проводит поиск связанной с проблемой информации в архиве спецификаций и в задачах. Если проблема связанна с функционированием системы для пользователя — проводится поиск в нормативных документах «Как оно должно быть по закону», если проблема связана со взаимодействием с другими системами — проводится поиск в описании витрин и API этих систем.
   1. Составляется список выявленных противоречий и мёртвых ссылок вида «В почте поступило требование от функционального заказчика сделать так», без подтверждающих материалов.
   2. При наличии доступа в репозиторий — проверяется фактически проведённое в привязанному к задаче коммиту.
   3. Если доступен разработчик, написавший код в прошлый раз, необходимо поинтересоваться у него, помнит ли он ограничения, заложенные в имеющееся решение, что именно заменил новый код или кто был инициатором задачи по его написанию.
   4. При наличии контакта с командой, владеющей другими системами, критически важные моменты в описании и правильности понимания уточняются у них.
      1. При отсутствии контакта — переписка эскалируется на уровень менеджмента. Иногда это не помогает. Это записывается в перечень проблем.
4. Собранная информация анализируется, в итоге синтезируется первичное решение (процесс идентичен аналитике для новых функций (будет описана позднее), но с критически важным учётом legacy-контекста и ограничений, выявленных на предыдущих шагах).
   1. Перед синтезом решения полезно визуализировать, что известно, а что — нет. Разделите лист или страницу на области: «Известные требования», «Известный код/логика», «Известные ограничения», «Гипотезы», «Белые пятна». Это наглядно покажет, на чём основано будущее решение, а какие его части зыбки и требуют дополнительных изысканий или явных допущений. Такую карту потом можно приложить к задаче на исправление.
5. Составляется предварительное описание «Как оно должно работать на самом деле» с разметкой сомнительных и вызывающих опасение мест.
   1. Если есть функциональный владелец — описание относится к нему для предварительного ревью и оценки. В этот момент могут всплыть недостающие исторические детали и неучтённые задачи, связанные с функциональностью. Описание уточняется.
6. Материалы готовятся для ознакомления с ними тим-лидом аналитики, далее, при необходимости, менеджером продукта и релиз-менеджером.
   1. При ознакомлении лидов и менеджеров с предварительным описанием «Как оно должно работать на самом деле» нужно обязательно указать на отличия от «Как оно работает сейчас» (или «Как оно не работает, но должно работать по обрывкам описаний»). Здесь может понадобиться цикл обсуждений, особенно если затронуты критичные части системы.
      1. В этот момент проблема может уйти на эскалацию продакт-оунеру для принятия решения на его (её) уровне.
7. После того, как желаемое состояние системы описано в confluence и утверждено (хотя бы на уровне тим-лида аналитики) — готовится задача на исправление, потом knowledge transfer для разработки под запись.

Скорее всего возникнут следующие проблемы:

1. Ответ от команд смежных подсистем не будет получен вовремя либо не будет получен вовсе, и эскалация в менеджмент не поможет.
   1. Не слишком существенная проблема (оказывающая минорное влияние на систему или затрагивающая малое число пользователей) имеет в этот момент шансы снова утонуть, так и не будучи решённой.
2. Причина появления проблемного куска кода (структуры БД) останется неизвестной.
3. Частная проблема вызовет глобальные изменения в проекте (например — инциирует редизайн пользовательского интерфейса).
4. Исправление частной проблемы потребует регресс-тестирование проекта как минимум в части связанной функциональности (использующей тот же код или те же таблицы в БД) и породит новые проблемы.
5. Проблема на некоторое время зависнет на два-три уровня выше в структуре принятия решений, поскольку потребует согласования между продакт-уонерами взаимодействующих систем.
6. Менеджмент «утонул» в эскалациях по критичным вопросам и перегрузился проблемами.

Блокирующими проблемами при этом будут только 1 (потому, что аналитик может вести изыскания только в доступной ему документации) и 5 (потому, что требуется стратегическое (политическое) решение). 3 и 4 — это расходы времени разработки, а 2 — просто неудовлетворённое любопытство аналитика (и, возможно, менеджеров и разработчиков). 6 — это повод искать выход на документацию и конкретных специалистов смежных систем.

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

1. Код в комментарии ссылается на задачу в системе управления проектом. Выгода для разработчика: меньше отвлечений на расследование новых инцидентов, связанных со старыми задачами и разработанным в них кодом.
2. Задача в системе управления проектом содержит описание формата: «Мы сделали так, потому что иначе нельзя было из-за [система X, закон Y, отсутствие времени Z]» и ссылку на документацию в конфлюенс (иной системе управления знаниями и документацией по проекту). Выгода для аналитика и менеджера: контекст решения теряется первым. Закрепление его в задаче — способ сохранить причину выбора решения.
3. Документация в системе знаний содержит настолько актуальное описание системы, насколько это возможно, и ссылки на эпики, связанные с описанной функциональностью. Выгода для команды: простота восстановления контекста при возвращении к доработке функциональности системы или для исправления проблем.

Внедрять эту культуру должны менеджеры и тим-лиды. Но обосновать её необходимость должен аналитик, заручившись поддержкой команды (в ходе разговоров или на ретроспективе).

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

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

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

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

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

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

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

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

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

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

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

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

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

https://t.me/ptz_ux_disperse — канал в телеграмме. Туда копируются статьи отсюда. Там есть обсуждение.
https://habr.com/ru/users/newintellimouse/posts/ — блог на Хабре. Аналогично, но не всё.

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

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

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

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

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

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

Выводы

1. Добиваться «подписи». У документации (backlog, спецификация) должно быть явное согласие ключевых стейкхолдеров: «Да, я обязуюсь по этим условиям».
2. Вести «протокол разногласий». Вторичная функция аналитика — история изменений, возражений, ограничений — это не архив, а прецедентное право. Она позволяет в будущем быстро разрешать споры, ссылаясь на уже принятые решения.
3. Говорить на языке сторон. С бизнесом — о ценности, метриках, проблемах пользователей. С разработкой — о логике, данных, состояниях системы. Аналитик — переводчик между оргструктурами.
4. Ценить свою роль. Аналитик — не overhead (накладные расходы), а страховка от рисков недопонимания, которая экономит команде сотни часов и бизнесу — тысячи (если не миллионы) рублей.

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

И нет, потребности организма и личности нельзя отодвигать на второй план в сравнении с требованиями работы.
От этого страдает качество принимаемых решений и выдаваемых ответов.
Любой человек, конечно, в первую очередь должен быть сыт, здоров и благополучен настолько, насколько это для него в текущих возможно, но если на автоматическую выдачу ответов переключается системный аналитик, то почему бы не заменить его AI?

Разумеется, я часто не следую этим правилам сам.

Умение вовремя тормозить и думать вообще противоречит моему воспитанию.