Итак, вы нашли своего идеального кандидата. Возможно, он даже очень силён, но спустя 2 месяца всё ещё не вышел на ожидаемую продуктивность. Более того, вы заметили, что производительность команды только снизилась, потому что другие инженеры тратят время на онбординг нового человека.
Наверное, я не открою Америку, если скажу, что это довольно тревожный сигнал.
Причём часто в проекте уже есть документация. Очень много документации. Есть обучающие вебинары по продукту, отдельный портал со всеми схемами, ссылки на внутренние страницы, доступы, инструкции, записи созвонов и ещё несколько документов “это обязательно прочитай”. Но почему-то это всё равно не помогает быстро войти в систему.
Почему?
Потому что слишком много информации, высыпавшейся на голову даже очень квалифицированному человеку, часто работает как отсутствие информации. Формально информация есть, ее даже много. Практически человек всё равно не понимает, с чего начать, что важно прямо сейчас, а что можно оставить на потом.
Исследования информационной перегрузки показывают, что избыток информации становится проблемой сам по себе: ухудшает принятие решений, снижает продуктивность и создаёт когнитивное давление.
Моя гипотеза в том, что каждый кусочек информации, который мы даём новому инженеру, должен быть максимально выверен. Это должен быть минимум на каждом этапе, который даст максимум понимания.
В идеале это помогает сократить время онбординга: команда меньше тратит время на повторяющиеся объяснения, новый человек быстрее выходит на самостоятельность, а сама система становится понятнее не только новичку, но и тем, кто давно в ней работает.
В этом цикле статей я попробую показать свой подход к понятному инженерному онбордингу на примере ThemeParks.wiki / parksapi — open-source проекта про данные парков развлечений: аттракционы, расписания, live data и очереди.
GitHub проекта: https://github.com/ThemeParks/parksapi
Важно: я вообще не утверждаю, что у команды ThemeParks.wiki есть проблемы с онбордингом, у меня нет данных об их процессах. Я использую проект как удобный публичный пример: у него открытый код, понятная предметная область и достаточно данных для внешнего разбора. И я люблю парки развлечений)
В первой части цикла я предлагаю представить себя новым разработчиком parksapi и попробовать первично понять продукт без погружения в код.
Важно ещё и про масштаб. Я не беру здесь систему уровня крупного банка со ста микросервисами, где один только верхнеуровневый обзор может превратиться в отдельную книгу. parksapi выглядит скорее как хороший пример среднего по сложности продукта: достаточно небольшой, чтобы его можно было публично разобрать в статье, и достаточно насыщенный, чтобы там были реальные интеграции, API, live-данные и доменная модель. В больших компаниях такой подход тоже применим, но время и глубина разбора будут совсем другими.
К концу статьи у нас должно получиться 3 артефакта первого дня:
короткий словарь системы;
первая black-box модель;
список вопросов для следующего погружения.
Не полная архитектура, не аудит проекта и не ревью кода. Только минимальная карта, которая помогает перестать тонуть.
Метод дня 1: найти опорные точки
Ответим всего на 3 вопроса:
Что система делает?
Какими сущностями она мыслит?
Где, вероятно, находится основная сложность?
Для этого я смотрю пока на три слоя:
интерфейс — что продукт показывает наружу;
API-документацию и Swagger — как система описывает свои данные;
README / репозиторий — как проект сам объясняет свою техническую роль.
В огромных компаниях иногда можно жить внутри одной фичи и не знать соседние части системы. Это отдельная модель работы. Но в небольших и средних командах, где один человек часто влияет сразу на несколько частей продукта, ширина взгляда становится огромным преимуществом.
Быстрый срез интерфейса
Первый проход по сайту я использую, чтобы собрать первые гипотезы и выявить основные сущности системы.
С главной страницы понятно, что речь идёт не просто о каталоге парков развлечений, а о real-time системе с данными по паркам: очереди, статусы работы, расписания. Это сразу наводит на главный вопрос: кто и как поддерживает это real-time чудо в актуальном состоянии? Это присылают парки, или это опрашивает проект? Кто заинтересованная сторона?
Сначала у меня появилась гипотеза, что продукт может быть полезен обычным посетителям для планирования маршрута по парку. Например, я как посетитель хотела бы получить готовую подсказку куда идти сейчас (где очередь меньше).
Но по ходу просмотра сайта эта гипотеза начала слабеть. Почти на каждом экране я увидела упоминания API: ссылки на source, API reference, JSON-представления сущностей.
Поэтому мой промежуточный вывод после интерфейса такой: сайт, похоже, не главное B2C-приложение, а скорее explorer API. Основная ценность, вероятно, находится в программном доступе к этим данным.
Ключевые слова, которые я вытащила из интерфейса:
парк
аттракцион
расписание
очередь
статус
live data
API
source
Это ещё не модель системы. Это словарь. Но для первого дня онбординга словарь уже полезен: мы перестаём смотреть на продукт как на набор случайных страниц и начинаем видеть повторяющиеся понятия. Более того, когда в голове есть иерархия понятий, разговоры на дейли уже будут не такими абстрактными, инженер будет понимать уже как минимум о какой части системы идет речь и в какой связке она находится с другими частями.
Дальше к прочтению очевидно просится API-документация, сайт настойчиво меня к ней ведет.
API-документация: где появляется модель
API-документация быстро уточняет гипотезы.
Если интерфейс дал первые слова — парки, аттракционы, очереди, статусы и расписания, — то API показывает более строгую модель: Destination, Park, Attraction, Show и Restaurant.
А еще тут есть отличная минималистичная схема, которую я бы забрала в артефакты первого дня. Замечательная схема.
Особенно интересным мне показался уровень Destination. Из интерфейса он был вообще не очевиден, но в документации видно, что Destination является родительским уровнем для парков и связанных сущностей.
Там же становится понятнее целевая аудитория: проект создан для разработчиков, которые хотят получать данные по паркам для своих приложений и исследований. Сам parksapi собирает данные в реальном времени, например статусы и очереди, а также статическую информацию, которая обновляется реже. Этот этап ответил мне на вопрос кто заинтересованная сторона и кто собственно собирает данные - сам parks api.
После этого раздела модель становится заметно яснее: у системы есть две стороны.
Первая — собрать и нормализовать данные из разных источников.
Вторая — дать разработчикам интерфейс доступа к этим данным через API (+ самим на сайте отобразить).
И вот здесь появляется первый сильный вывод: похоже, основная ценность системы не в сайте как таковом, а в нормализации данных из разных парков и предоставлении единой модели наружу.
Swagger: уточняем словарь системы
Swagger помогает уточнить не только endpoints, но и сам словарь системы.
По TypeDoc видно, что все основные объекты описываются через общий тип Entity: у них есть единый набор базовых полей, а конкретный вид задаётся через entityType.
Базовые типы сущностей не отличаются от описанных в API документации:
Дальше вокруг этих сущностей крутятся несколько слоев данных:
metadata
children
live data
schedule
metadata отвечает на вопрос “что это за объект?”.
children — “что находится внутри?”.
live data — “что с ним происходит сейчас?”.
schedule — “когда он работает?”.
Live data - интересное поле. Например, у очередей есть разные варианты: standby, single rider, return time, paid return time, boarding group и другие.
Для первого слоя этого достаточно: parksapi приводит разные объекты разных парков к общей модели сущностей, а затем даёт возможность получить по ним базовое описание, дочерние сущности, live-состояние и расписания через API.
Это уже хороший словарь для нового человека.
README: где находится техническая сложность
README опять же подтвердил основную гипотезу: центр системы не в интерфейсе, а в сборе и нормализации данных.
Сам проект описан как open-source TypeScript-библиотека для получения real-time данных по паркам: очередей, расписаний и metadata сущностей. Эта библиотека питает бесплатный API ThemeParks.wiki.
В примере использования почти сразу видны три ключевых действия:
получить сущности
получить live data
получить расписания
То есть модель из API-документации становится ещё устойчивее: система строится вокруг entities, live data и schedules.
README также уточняет, откуда берётся сложность: проект поддерживает 75+ destinations и для большинства парков требует отдельные API credentials. Очень интересно, удалось ли как-то унифицировать этот интерфейс входа, или каждый новый парк - боль. Значит, перед нами не просто каталог парков, а integration-heavy система, которая должна подключаться к разным источникам, собирать данные и приводить их к единому виду.
Внутреннюю архитектуру README тоже немного приоткрывает, но для первого дня онбординга я пока не хочу проваливаться глубже. Это уже следующий слой. На этом этапе достаточно зафиксировать главный вывод:
parksapi собирает данные из разных источников, нормализует их и отдает наружу через API.
Первая модель: что система делает в целом
Теперь можно собрать первую модель.
В первом приближении мне важно показать систему в black-box виде: что она получает на вход, что делает внутри и что отдаёт наружу.
Да, схема выглядит очень простой. И да, команда, которая живёт внутри проекта, может набросать такую за 5 минут. В этом и весь смысл: если первый артефакт можно сделать быстро, тем страннее каждый раз заставлять нового человека собирать его самостоятельно.
Хороший артефакт первого дня не должен поражать сложностью, наоборот, он должен поражать легкостью, давать опору. После такой схемы проект уже не выглядит как “какой-то сайт про парки”. Он превращается в понятную цепочку:
собрать данные → привести к общей модели → отдать через API.
Это и есть первый слой понимания.
Выводы и артефакты первого дня
Главная задача первого дня была перестать смотреть на проект как на непонятное нечто и составить четкое краткое представление.
После прохода по интерфейсу, API-документации, Swagger и README у нас уже есть несколько устойчивых выводов:
1. ThemeParks.wiki выглядит скорее как explorer / витрина поверх API,
чем как главное B2C-приложение.
2. Центр системы находится в сборе и нормализации данных.
3. Базовая доменная модель строится вокруг:
Destination, Park, Attraction, Show, Restaurant.
4. Ключевые API-слои вокруг сущностей:
metadata, children, live data, schedule.
5. Главная техническая сложность, вероятно, связана с интеграциями разных источников и приведением данных к единому виду.
Артефакты первого дня получаются довольно компактными:
1. короткий словарь сущностей;
2. black-box схема системы;
3. список вопросов для следующего погружения.
Такие артефакты, кстати, полезны не только новым разработчикам. Понятная карта системы часто нужна и людям, которые не пишут код каждый день: продактам, продажам, саппорту, менеджменту. Чтобы не было так, что мы что-то пообещали клиенту, потому что казалось что это легко, а оказалось вовсе не так. Мне кажется, это часто проседает не меньше, чем инженерный онбординг. И, конечно, большое уважение вызывает СЕО, который понимает из чего состоит его продукт.
Вопросы на следующий день:
откуда именно приходят данные парков;
как устроены адаптеры для разных destinations;
где проходит граница между статическими и live-данными;
как работает кеширование;
насколько легко добавить новый парк;
где находится самый “жирный” кусок системы, который даст максимум понимания.
Именно это я и называю “убрать хаос”: найти минимальную модель, которая помогает удержать систему в голове.
В следующей части можно будет сделать следующий шаг — найти ядро проекта, те самые 30% системы, которые дадут 70% практического понимания.