Domain Vision Statement

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

Вот приходите вы в новую команду, уже успели прочитать базовую документацию для знакомства с проектом и предметной областью, подходите к наставнику, а он вам: “Давай расскажу суть проекта, познакомлю со структурой и с чем придётся работать в ближайшее время.” И далее обычно следует, действительно, короткий, но очень ёмкий, точный, последовательный и понятный рассказ. Рассказ, которого вы не видели ни в документации, ни в README репозитория.

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

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

Вот ровно то, чтобы вы рассказали новому члену команды в первые 5 минут разговора. Два-три абзаца: просто, чётко и по делу. Это изложение должно определять цель и назначение проекта и конкретно данной кодовой базы.

Что включить в описание?

• Название проекта, понятное всем и каждому. Без сложных аббревиатур и терминов предметной области, т.к. с этим человек познакомится позже.
• Общая цель проекта. Какую основную задачу или проблему решаете. Возможно, тут придётся поверхностно пояснить небольшие особенности предметной области.
• Положение проекта в общей экосистеме. Как именно встраиваетесь в общее решение, описание назначения интеграций с внешними системами.

Не грузите деталями, которые могут измениться. Никаких микросервисов, баз данных или технологических особенностей! Основной фокус и упор — создание правильного представления о предназначении проекта.

Не получилось с первого раза?

Не страшно! Отлаживайте и итеративно дорабатывайте это описание. Можете начать с одного предложения или абзаца. Сделайте сами или попросите AI сгенерировать базовый вариант. Вы всегда сможете добавить необходимые детали, по мере своего погружения в предметную область.

Хорошо, давай пример!

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

Если однажды решу, что это описание не работает как нужно, сделаю его лучше и точней!

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

Ты не придумал ничего нового!

Да, верно. Эрик Эванс назвал это описание “Domain Vision Statement”, указывая, что оно задает разработчикам общее направление, на чем должны быть сконцентрированы все усилия. Фокус не на технологиях и алгоритмах, а на решаемой задаче. Именно эту эстафету и нужно передать на входе.

И ещё. Пишите не для себя в будущем, а для себя в прошлом! Пишите для незнакомца, который только-только начинает работу с проектом. И будет замечательно, если такие незнакомцы будут выступать основными рецензентами.

---

А что у вас в README корня репозитория? Как вы доносите суть до новичков?