Единый глоссарий предметной области (domain dictionary / глоссарий домена / словарь домена) в распределённой команде создаётся за 7 шагов: договориться о владельце и правилах, собрать термины из реальных артефактов, ввести формат «термин → смысл → пример», согласовать спорные слова через решения, встроить глоссарий в процессы (задачи/тесты/код), автоматизировать проверки и регулярно обслуживать как продукт.

Боль знакомая: один пишет «клиент», второй — «контрагент», третий — «пользователь», а в Jira это всё одна сущность, которая в базе данных называется customer_entity_v2. На созвонах люди кивают, а потом выпускают фичу, которая «почти то». В офисе это лечится наскоком к аналитикам, в распределёнке — копится как технический долг, только по смыслу, а не по коду.

Из практики: самое дорогое в проектах — не «плохой код», а «разные слова про одно и то же». Потому что код можно отрефакторить за спринт, а кашу в понятиях выковыривать приходится месяцами: в требованиях одно, в тест-кейсах другое, в поддержке третье. Поэтому domain dictionary — не документ «для галочки», а страховка от массового взаимонепонимания.

7 шагов: как собрать domain dictionary и не умереть в согласованиях

Шаг 1. Назначьте владельца и правила игры (иначе будет «общий файл, который никто не трогает»)

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

Обоснование: в распределённой команде «коллективное владение» часто означает «коллективное игнорирование». Особенно когда люди в разных часовых поясах и с разными контекстами (разработка, тестирование, бизнес).

Практический вывод: назначьте Domain Owner (часто это BA/PO/тимлид), и заведите правила: где хранится словарь домена, как вносить изменения, кто аппрувит, как решаются споры.

Подводный камень: пытаться демократично голосовать за каждое слово в общем чате. Спойлер: победит самый громкий, а не самый правый.

• RACI на глоссарий: кто Responsible / Accountable / Consulted / Informed.
• SLA на правки: например, спорный термин решаем за 48 часов.

Шаг 2. Соберите термины из «боевых» источников, а не из головы

Тезис: глоссарий домена не придумывают — его выкапывают из фактов.

Обоснование: в любой компании уже есть язык: в ТЗ, тикетах Jira, Confluence, регламентах, письмах, названиях полей в 1С, текстах на кнопках, обращениях в поддержку.

Практический вывод: сделайте выгрузку/инвентаризацию терминов: топ-100 слов, которые чаще всего вызывают вопросы и «уточни, что ты имеешь в виду».

Подводный камень: начинать со «все термины мира». Вам нужен MVP-словарь домена: то, что реально ломает коммуникацию прямо сейчас.

1. Берёте 20–30 последних задач в Jira/YouTrack.
2. 3–5 пользовательских сценариев (use cases) + 10 экранов UI.
3. Сущности из базы/интеграций (например, справочники 1С, события из Kafka, документы в СЭД).
4. 10–20 обращений в поддержку: там «живой язык» клиентов.

Шаг 3. Зафиксируйте шаблон записи: «термин → определение → пример → антипример»

Тезис: качество глоссария определяется не количеством слов, а единым форматом.

Обоснование: если один термин описан как «это когда…», другой — как «см. выше», третий — как аббревиатура без расшифровки, глоссарий превращается в свалку.

Практический вывод: введите карточку термина. Минимум: определение, контекст, пример в продукте, связи с другими терминами.

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

Шаг 4. Разрулите «спорные слова» через решения, а не через бесконечные обсуждения

Тезис: некоторые термины — это политика, а не лингвистика.

Обоснование: «клиент» может быть физлицом, юрлицом, лидом, пользователем портала — и каждый департамент будет прав по-своему.

Практический вывод: фиксируйте Decision Log: какое слово выбрали, почему, какие последствия для UI/БД/интеграций.

Подводный камень: пытаться всем угодить: «пусть будет и так и так». Потом у вас будет и так и так — в проде.

Мини-кейс (неудачный): команда делала внутренний сервис для продаж. В документации «сделка» = карточка в CRM, в базе «deal» = договор, в аналитике «deal» = лид. Через 2 месяца метрики конверсии стали «плясать», потому что разные отчёты считали разные сущности. Исправляли не код — смысл. Потратили спринт на унификацию и ещё один на миграции и переименование полей.

Шаг 5. Встройте словарь домена в рабочие артефакты: Jira, тесты, схемы, код

Тезис: если domain dictionary живёт отдельно, его читают только новички в первый день (и то если повезёт).

Обоснование: люди учатся по месту действия: в задаче, в Pull Request, в тест-кейсе, в API-спеке.

Практический вывод: сделайте ссылку на глоссарий обязательной частью шаблонов: Definition of Ready/Done, PR checklist, шаблон user story.

Подводный камень: «глоссарий в Confluence, но доступ только у половины команды». В распределёнке это частая история: подрядчики, партнёры, смежники.

• В Jira: кастомное поле «Термины» (ссылки на карточки).
• В Swagger/OpenAPI: единые названия моделей и описания полей по глоссарию.
• В тестировании: BDD/Gherkin сценарии с терминологией из словаря домена.

Шаг 6. Автоматизируйте «подсветку» нарушений: хотя бы на уровне линтеров и шаблонов

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

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

Практический вывод: минимум — автозамены/подсказки в документации и шаблоны. Максимум — проверки на запрещённые термины в PR (простые скрипты по markdown/админке документации).

Подводный камень: делать «полицию слов» без здравого смысла. Если термин реально меняется — меняйте глоссарий, а не ругайтесь с реальностью.

Шаг 7. Обслуживайте глоссарий как продукт: метрики, регулярные ревизии, онбординг

Тезис: глоссарий домена устаревает так же быстро, как и требования.

Обоснование: новые интеграции, новые тарифы, новый модуль в 1С, переезд на другой процесс — всё это меняет язык.

Практический вывод: заведите ритуал: раз в 2–4 недели ревизия изменений, раз в квартал — «генеральная уборка» (архивация, объединение дублей).

Подводный камень: хранить старые определения без статуса. Добавьте метки: Draft/Approved/Deprecated, иначе новички будут учить «термины-призраки».

Если хочется примеров артефактов (карточка термина, лог решений, шаблоны Jira/Confluence) — на itokno.ru периодически появляются такие разборы без маркетинговой пены, с тем, что реально можно утащить в работу.

Экспертный вердикт и инструмент

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

• Есть владелец: понятно, кто принимает финальное решение по термину.
• Есть единый шаблон: термин, определение, пример, антипример, синонимы, владелец.
• Есть Decision Log: спорные слова фиксируются как решения, а не как бесконечные треды.
• Глоссарий встроен в процессы: ссылки в задачах, API-спеках, тестах, PR.
• Есть статусы: Approved/Deprecated, чтобы не учить «мёртвые» понятия.
• Есть регулярная ревизия: раз в спринт/месяц, а не «когда-нибудь».

Частые вопросы