Ведение глоссария проекта как общего словаря

Цель

Одно место, где каждый термин проекта в коде, интерфейсе, документации и разговорах имеет одно значение, чтобы «account», «customer» и «tenant» не обозначали незаметно одно и то же в трёх местах и разные вещи в четвёртом.

Предварительные условия

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

Шаги

1. Составьте исходный список из существительных в модели данных, ресурсов API и всех терминов, которые вызвали непонимание при ревью или инциденте.
2. Используйте единый формат записи: термин; определение одним предложением; чем он не является (близкие синонимы и различия); пример; где встречается (таблица, поле, конечная точка, экран); статус (предпочтительный, устаревший с указанием замены, избегать).
3. Выберите ровно один предпочтительный термин для каждого понятия. Создайте для отвергнутых синонимов записи со ссылкой на предпочтительный термин, чтобы поиск по неправильному слову всё равно приводил куда нужно.
4. Раскрывайте сокращения при первом использовании в каждом документе и в самой записи. Цитируемый RFC 7322 говорит, что сокращения следует раскрывать в заголовках документов и при первом использовании; цитируемое руководство Google по стилю просит определять необходимый профессиональный жаргон при первом использовании или давать ссылку на надёжное определение.
5. Свяжите первое появление термина в документе с его записью, вместо того чтобы заново определять его прямо в тексте: встроенные определения расходятся со временем.
6. При переименовании понятия измените глоссарий тем же коммитом, что код и документацию, пометьте старый термин как устаревший с датой и сохраняйте его в течение цикла выпуска, чтобы старые журналы и задачи оставались понятными.
7. Проверяйте глоссарий при изменении модели данных и при каждом выпуске; удаляйте записи, на которые никто не ссылается.

Ожидаемый результат

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

Ограничения и основание проверки

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

Область действия по ограниченному контексту

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