Как мы составляем глоссарий для сложной технологической платформы

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

Мы — часть команды документирования платформы Platform V в СберТехе: Лидия Ковач, middle технический писатель, Мария Бурханова, senior технический писатель, и Светлана Каюшина, руководитель команды. Хотим рассказать, как мы разработали глоссарий, который повысил качество документации нашей цифровой платформы для построения ИТ‑ландшафта.

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

Работа с терминологией — это непросто, но в случае с Platform V задача была ещё сложнее. Нам нужно было не просто стандартизировать несколько терминов, а создать полноценный глоссарий для сложной платформы с сотнями терминов из областей кибербезопасности, работы с данными, интеграции, инфраструктурных решений и инструментов ИТ‑разработки.

Мы начали с того, что вручную собрали термины из нашей документации: объединили уже существующие глоссарии всех продуктов, попытались сделать единые определения для повторяющихся терминов. Но различия в написании одних и тех же терминов привели к путанице, а отсутствие чётких критериев отбора терминов усложнило задачу. Поэтому мы попробовали разделить глоссарий на категории: выделили общие для всех продуктов термины (например, «API», «Kubernetes») и специфичные (например, «шард» — термин интеграционных сервисов).

Тут мы ещё сильнее запутались и пересмотрели категории: общие термины (например, «API», «Kubernetes»), платформенные термины (специфичные для Platform V) и термины, для которых важно было зафиксировать именно написание, а не определение (например, «pod» или «под»). Но этот подход привёл к избыточному количеству глоссариев без ясной цели и структуры.

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

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

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

1. Cбор и обработка списка терминов: анализ и фиксация написания, составление структуры глоссария (какие разделы словарной статьи нам нужны).
2. Добавление определений: применение традиционных методов наряду с технологиями искусственного интеллекта.

Этап 1. Что считать термином

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

Определение целевой аудитории

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

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

Сбор терминов

Мы воспользовались инструментом для выделения ключевых слов и фраз из русскоязычных текстов. Он принимает во внимание следующие критерии и метрики:

• частотность: определяет повторяемость слов или фраз в тексте (мы установили порог в пять повторений для охвата максимума терминов для последующего анализа);
• вес (TF‑IDF): оценивает значимость слова в документе относительно корпуса текстов;
• длину: выделяет фразы из 1–3 слов как предпочтительные;
• фильтрацию стоп‑слов: исключает распространённые слова (например, предлоги);
• морфологию: приводит слова к начальной форме с помощью библиотеки pymorphy2;
• контекст: выявляет устойчивые выражения через анализ сочетаний слов.

Инструмент мы доработали, чтобы получить дополнительные метаданные. Например, поддержали настройку уровней гранулярности (GRANULARITY) для группировки файлов по коду, версии продукта и названию документа, в котором упоминался тот или иной термин. Это очень помогло нам в дальнейшем.

Когда мы убрали дублирование, осталось 23 311 потенциальных терминов.

Структура глоссария

Примерно так выглядела первая итерация работы с данными:

Описание таблицы:

1. Термин — отобранный из 23 311 слов список. Оставили 213 слов, которые:

• вызывают сложности при выборе написания;
• содержат частые ошибки;
• требуют определений.

2. Упоминания — различные варианты написания из файла с 697 567 неуникальными строками. Помогает решать спорные случаи и фиксировать рекомендации в столбцах «Используем», «Аналог», «Не используем».

3. Используем — предпочтительное написание термина.

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

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

6. Не используем — «чёрные списки» из файла с 697 567 неуникальными строками для контроля качества документации.

Латиница или кириллица

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

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

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

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

Финальная вычитка и сбор обратной связи

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

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

Автоматизированные проверки

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

Правила проверки реализованы в валидаторе Platform V GetDocs, нашего инструмента для разработки документации в парадигме Docs‑as‑Code. Инструмент позволяет преобразовывать исходные тексты документации из разных источников в выходные формы и размещать их на веб‑сайте для пользователей. При сборке документации формируется отчёт с перечнем терминов, не соответствующих глоссарию. Например, термин «node» помечается как ошибка, если в глоссарии указан вариант «узел».

Этап 2. Что термин означает

Мы составили список терминов и занялись их описанием. Классический способ — сбор определений из различных источников и дальнейшая их унификация — показался нам проблематичным. Какие источники считать надёжными? Сколько времени продлится эта работа (спойлер: по нашим оценкам, около полугода‑года)?

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

(backup)=

Бэкап

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

Пример употребления: перед обновлением продукта рекомендуется сделать бэкап базы данных

Допустимые аналоги: резервное копирование

Нерекомендуемые синонимы: бекап; backup; бекапить

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

Заключение

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

Конечно, нужно учитывать, что это исключительно наш опыт — разработка глоссария делалась параллельно с другими задачами и растянулась во времени. Глоссарий может изменяться (например, в отношении англицизмов) и требует регулярных обновлений: мы добавляем 5–10 новых терминов ежемесячно на основе предложений команд. Сейчас в нашем глоссарии уже более 500 терминов.

Вот наши рекомендации для тех, кому предстоит решить похожую задачу:

1. Определите целевую аудиторию.
2. Соберите корпус текстов.
3. Настройте инструмент для автоматического извлечения терминов.
4. Создайте чёткую структуру глоссария (например, термин, рекомендуемое написание, недопустимые формы, английский оригинал и примечания).
5. Реализуйте автоматические проверки соблюдения глоссария в текстах.
6. Используйте ИИ для ускоренного составления определений.
7. Регулярно поддерживайте и обновляйте глоссарий.

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

Мы уверены, что многие команды проходили этот путь — какие подходы к глоссариям используете вы? Делитесь в комментариях, расскажите про ваш опыт, подводные камни и советы на будущее, будем рады!

P. S. Искренне благодарим всех, кто участвовал в разработке глоссария и работал с терминологией Platform V. Всем, кто в принципе причастен к работе с терминологией, низкий поклон. Это действительно огромный труд!