Всем привет!

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

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

Что делать, когда попал в проект без документации? Ответ простой — уходить!

А если серьёзно, то отсутствие документации — это большая возможность для прокачки скиллов — как хардов, так и софтов. Мне приходилось собирать информацию по крупицам, фиксировать её и минимизировать bus‑фактор.

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

В статье постараюсь придерживаться следующих рамок:

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

• Будем считать, что документация на проект отсутствует или очень устарела — что ещё хуже, так как она может вводить в заблуждение.

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

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

• Сразу бы хотелось оговориться, что в некоторых пунктах как вариант решения проблемы будет упомянуто самостоятельное чтение кода. Некоторые аналитики намеренно избегают этого. На самом деле многие фреймворки написания программного обеспечения базируются на паттерне MVC, и если понять подход данного паттерна, чтение кода становится кратно проще.

• Ну и для поднятия настроения при чтении статьи я буду использовать мемы.

Итак, с чего начать восстанавливать доку

Так что же делать, с какими проблемами придётся столкнуться — опытным путем я для себя вывел минимальный и достаточный для погружения в проект объём шагов. Это своего рода чек‑лист с проблемами, решив которые, на мой взгляд, довольно глубоко можно погрузиться в проект и снизить bus‑фактор.

Я выделил следующие проблемы с документацией:

1. Нет зафиксированных бизнесовых сценариев, которые решает продукт, например, в виде User Story, что мешает вам в целом понимать, какие бизнес проблемы вы решаете своим продуктом.

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

3. Отсутствие зафиксированных архитектурных решений, как следствие — нет понимания, как взаимодействуют между собой микросервисы (через REST, SOAP, брокеры сообщений и т. п.). А может быть, вы выясните, что у вас и вовсе монолит.

4. Отсутствие сиквенс-диаграмм, которые в последнее время в аналитике стали чуть ли не обязательными, нельзя понять, какие микросервисы вызывают какие эндпоинты во внешнем мире и в какой последовательности.

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

6. Если у вас нет зафиксированной логики работы сервисов, вам будет сложно анализировать инциденты, прилетающие с прода, поэтому этот пункт также важен.

Далее в ходе статьи разберём для каждого пункта данной дорожной карты способы решения и возможные варианты итоговых артефактов.

Определение бизнес-сценариев

Как мы ранее обусловились, по легенде аналитик попадает на проект онлайн‑магазина детских игрушек. На онбординге он не находит в условном Конфлюенсе описанных бизнес‑сценариев, которые покрывают разрабатываемое приложение. Я выделил для себя несколько шагов для решения:

1. Получить доступ к тестовому стенду системы и попробовать интуитивно понять, какой функционал есть в системе. Так можно зафиксировать часть реализованных User Story. На этом этапе вы сможете понять, насколько хорошо продуман UX‑дизайн и подсветить команде сложности навигации в системе.
   
   Наверняка в нашем магазине детских игрушек есть не только возможность класть товар в корзину и оплачивать его. Вероятно, можно сравнивать разные товары, оценивать их, оставлять отзывы и т.п. Всё, что находим — фиксируем.

2. Отдельным пунктом выделю определить круг стейкхолдеров продукта и подготовить вопросы для интервью. Иногда найти ответственного не всегда так просто, как кажется.

3. После того, как вы самостоятельно нашли какой‑либо объём сценариев в пункте 1 — их нужно провалидировать при помощи стейкхолдеров и членов команды. Вероятно, вы получите ряд уточнений.

4. Провести интервью со стейкхолдерами и представителями команды, которые ближе к бизнесу (менеджеры проекта/продукта) — здесь вы, вероятно, получите дополнительные сценарии, которые не нашли самостоятельно. Например, сможете узнать, что для разных ролей есть разные сценарии, и ваше мобильное приложение доступно не только покупателям, но и продавцам для сборки онлайн-заказов.

Отмечу, что этот набор пунктов нужно пройти итерационно несколько раз (кроме, пожалуй, второго пункта). В каждой итерации можно узнать всё новые нюансы.

В качестве артефактов фиксации бизнес‑сценариев выделю:

• Зафиксированные User Story

• BPMN‑диаграммы в одной из первых итераций

  

• Зафиксированные Use Case для различных User Story

  

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

Но расслабляться ещё рано, мы коснулись лишь вершины айсберга.

Определение перечня сервисов проекта

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

1. Интервьюирование коллеги, стоявшего у истоков, он может вам помочь (но это неточно). Это может быть тестировщик, аналитик, разработчик или любой другой сотрудник. В начале статьи мы договорились, что знания у всех «кусочные». Примем допущение, что у коллеги мы всё-таки смогли получить часть информации.

2. Изучение системы контроля версий (условный GitLab) — позволит найти ещё часть сервисов, в которые контрибьютили ваши коллеги‑разработчики.

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

4. Не забываем, что в начале статьи я упомянул, что часть команды уже уволилась. В процессе интервью «выжившие» могут не вспомнить сервис, который разрабатывал условный Вася, уволившийся два года назад, а его сервис ещё в проде. Тогда нам может помочь таск‑трекер (условная Jira). В эпиках создания сервисов может фигурировать информация о том, какие сервисы нужно было разработать или доработать. Вы увидите, что ранее Вася создавал сервис, о котором вам никто не рассказывает.

После исследования сервисов у вас как минимум должны появиться дополнительные артефакты:

1. Зафиксированный список сервисов, участвующих в разрабатываемой системе. На данном этапе можно их отображать просто квадратиками. 

   

2. Найдены Swagger, ReDoc, WSDL документации по всем сервисам проекта. 

   

3. Найдены примеры запросов (cURL‑ы).

4. Найдены хосты стендов, параметры аутентификации и авторизации.

5. Возможно, вам удастся раздобыть коллекции условного Постмана — это будет просто отлично, сильно упростите себе жизнь.

Теперь, вероятно, вы будете выглядеть как-то так:

К этому моменту будет примерно понятен масштаб бедствия — количество сервисов, которые вам нужно описать.

Определение архитектурных решений

После предыдущих двух шагов у вас есть представление, что клиенты могут делать в онлайн-магазине детских игрушек и из каких микросервисов на бэкенде он состоит. Пришло время выяснить, как взаимодействуют микросервисы между собой и узнать, как они общаются между собой: через REST, SOAP или брокеры сообщений. На этом шаге важно определить, между какими микросервисами есть взаимосвязь, а какие между собой не общаются.

1. Если у вас веб-приложение, начать проще всего самим. Через инструменты разработчика (на Windows это F12, скрин ниже) находим во вкладке Network, к каким эндпоинтам обращается фронтенд.

   

2. Сопоставляя имеющуюся документацию Swagger, можем понять, в какой сервис обращается фронт. Скорее всего, на этом шаге будет один сервис, но это неточно.

3. Всё, что за вашим первым сервисом back-end, вы не увидите через инструменты разработчика. Есть два пути уточнения:
   — если умеете читать код, можно получить доступ к гиту сервисов, которые используются в вашей системе, и продолжить изучение самостоятельно;

   

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

Пример: условный разработчик Вася делал gateway, который ходит в сервисы 4,5,6 — Вася вам это точно сможет сказать. А разработчик Миша, который разрабатывал сами сервисы 4,5,6 — достоверно не скажет, какие сервисы к нему обращаются. Поэтому в данном примере более ценным интервьюируемым будет разработчик gateway Вася, но и пообщаться с Мишей будет не лишним, так как его сервисы могут вызывать ещё какие‑либо внешние сервисы.

На этом этапе мы можем получить артефакты:

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

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

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

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

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

Фиксация диаграмм последовательности

После предыдущего шага мы в целом знаем, как и какие сервисы взаимодействуют между собой. Мы, вероятнее всего, даже можем создать через Постман тестовый заказ, дёрнув соответствующую ручку. Но вызвав сервис напрямую вручную для создания заказа, мы не воспроизведём полностью Use Case клиента и явно можем упустить важные нюансы с точки зрения последовательности вызовов микросервисов.

1. Для полноценного воспроизведения Use Case с точки зрения бэкенда я использовал логи. Зная запрос с фронта на бэк (который мы нашли через инструменты разработчика на предыдущем шаге), — берём в логах данного запроса идентификатор запроса (как правило, его называют request_id) и далее фильтруем все логи по данному параметру. Так мы увидим все эндпоинты, задействованные в Use Case.

   

2. Если у вас в логах по какой‑то причине нет идентификатора запроса или он не «пробрасывается» через всю систему, после получения эндпоинта с фронта на бэк для всей дальнейшей цепочки запросов придётся либо изучать код, либо обращаться за помощью к разработчикам.

3. Далее мы сопоставляем все полученные на данном шаге эндпоинты и схему взаимодействия сервисов из предыдущего шага и получаем sequence-диаграмму.

Собственно артефактом после данного шага будет полноценная sequence-диаграмма. На этом шаге вы сможете полноценно вручную проходить клиентский путь через Постман или подобные ему инструменты. Ниже представлена всего одна упрощенная диаграмма последовательности, но у вас должно получиться несколько схем для различных Use Case.

На примере интернет магазина игрушек у вас появится как минимум диаграмма для онлайн-заказа, для оставления обратной связи по товару и рейтингу товаров. Наверняка отдельными будут диаграммы последовательности для ролей сотрудников магазина, где они будут заняты сбором онлайн-заказов.

В итоге у вас получится несколько диаграмм последовательности, и вы можете немного побыть Дмитрием Нагиевым:

Определение структуры моделей данных

После того, как мы поняли бизнесовые сценарии нашего онлайн‑магазина игрушек, разобрались, какие сервисы под капотом вызываются для различных Use Case, нам предстоит узнать, какие вообще данные у нас хранятся в базе данных (далее — БД). Часть сущностей, которые есть в системе, мы смогли определить на шаге проработке бизнес-сценариев.

Наверняка ни один магазин не обходится без объектов Заказ, Платёж, Чек. Но какие ещё есть объекты в нашей системе, какие параметры данных объектов мы храним в БД — это очень важные вопросы для понимания возможностей системы.

1. Для начала нужно уточнить у разработчиков, какая у вас база данных: реляционная или не реляционная. Условимся, что у нас реляционная БД, пусть это будет PostgreSQL.

2. Далее самым верным шагом будет изучить структуру данных через подключение к БД (например, через терминал или инструменты визуализации интерфейса наподобие DBeaver).

3. Альтернативным сценарием будет самостоятельное чтение кода (Буква «М» из паттерна MVC, который упоминался в начале статьи).

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

На этом этапе в качестве артефакта, у вас появится описанная модель данных. Например, в виде ER-диаграммы.

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

Теперь, задокументировав эту информацию, вы приоткрыли завесу тайны и знаете о структурах объектов.

Определение логики работы сервисов

Теперь мы знаем про наш онлайн-магазин игрушек очень много, но осталось устранить важный пробел — начать понимать внутреннюю логику работы сервисов (в том числе маппинг параметров между сервисами).

Условно, какие параметры из заказа вставляются в объект платежа перед отправкой в платёжную систему и какие параметры платежа и заказа нужно отправлять в провайдер чеков, чтобы в будущем не попасть на неприятный разговор с Федеральной налоговой службой со всеми вытекающими последствиями.

Здесь на самом деле не так много вариантов, как получить информацию. Я для себя зафиксировал два варианта:

1. Самостоятельное чтение кода и последующую валидацию полученных блок-схем через тест‑кейсы.

2. Интервьюирование разработчиков сервисов системы.

В качестве артефакта здесь подойдут любые схемы, которые отразят логику работы приложения. Я встречал случаи, когда логику описывали просто текстом, но мне удобнее читать по блок-схемам, тут, как говорится, «на вкус и цвет».

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

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

Вместо выводов

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

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

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

На первый взгляд, статья содержит всего лишь шесть пунктов, что может создать впечатление, что восстановить документацию по данному роадмапу легко и быстро. На практике это долгий и трудоёмкий процесс. Не забывайте, что параллельно с восстановлением документации проект продолжает развиваться, и новые фичи также требуют аналитики. Это значит, для закрытия долга по документации нужно «бежать» быстрее всей команды, иначе размер техдолга останется тем же или будет увеличиваться.

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

Приходилось ли вам попадать в команду, в которой большой долг по документации? Если да, поделитесь в комментариях, в какой роли вы были и как справлялись с информационным вакуумом?