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

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

Мы — команда документирования платформы Platform V ^[1] в СберТехе. Хотим рассказать, как мы разработали глоссарий, который повысил качество документации нашей цифровой платформы для построения ИТ‑ландшафта. Поделимся тем, как устроен наш глоссарий, с какими трудностями мы столкнулись и какими инструментами пользовались. Надеемся, это поможет вам добиться точности и единообразия терминологии в вашей компании.

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

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

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

Чтобы не повторять ^[2] ошибки ^[3], мы изучили опыт ^[4] других компаний и сообществ, например, Cloud Native ^[5], проконсультировались с профессиональными переводчиками и локализаторами ^[6], а также приняли во внимание ^[7] наработки редакции Госуслуг ^[8]. В результате мы выявили ключевые проблемы предыдущих попыток:

• отсутствие чётко определённой целевой аудитории;

• непонятные критерии для формирования списка терминов;

• отсутствие механизма принятия решений относительно правильного написания терминов;

• сложности поддержки и актуализации глоссария.

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

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

2. Добавление определений: применение традиционных методов наряду с технологиями искусственного интеллекта ^[9].

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

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

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

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

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

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

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

• частотность: определяет повторяемость слов или фраз в тексте (мы установили порог в пять повторений для охвата максимума терминов для последующего анализа);

• вес (TF‑IDF): оценивает значимость слова в документе относительно корпуса текстов;

• длину: выделяет фразы из 1–3 слов как предпочтительные;

• фильтрацию стоп‑слов: исключает распространённые слова (например, предлоги);

• морфологию: приводит слова к начальной форме с помощью библиотеки pymorphy2 ^[11];

• контекст: выявляет устойчивые выражения через анализ сочетаний слов.

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

Анализ корпуса текстов Platform V дал Excel‑файл с 697 567 неуникальными строками:

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

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

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

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

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

   • вызывают сложности при выборе написания;

   • содержат частые ошибки;

   • требуют определений.

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

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

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

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

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

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

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

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

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

• выбираем кириллицу, если слово на кириллице и латинице встречается примерно одинаково часто;

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

Пример 1

Мы точно могли сказать, что при выборе между вариантами «pod» / «под» / «отсек»* слово «отсек» не будет понятно ни одному нашему пользователю, так как оно не встречается в нашем корпусе текстов ни разу. В то время как «под» используется 223 раза, а «pod» — 310 раз. «Под» попал в столбец «Используем», «pod» и «отсек» — «Не используем».

*«отсек» использует Иван Портянкин в книге «Программирование Cloud Native. Микросервисы, Docker и Kubernetes»

Пример 2

Слово «алиас» встречается 86 раз, «alias» — 50 раз, «псевдоним» — 196 раз. «Псевдоним» попал в столбец «Используем», «алиас» — в «Аналог», «alias» — в «Не используем».

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

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

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

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

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

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

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

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

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

(backup)=

Бэкап

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

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

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

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

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

Заключение

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

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

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

1. Определите целевую аудиторию.

2. Соберите корпус текстов.

3. Настройте инструмент для автоматического извлечения терминов.

4. Создайте чёткую структуру глоссария (например, термин, рекомендуемое написание, недопустимые формы, английский оригинал и примечания).

5. Реализуйте автоматические проверки соблюдения глоссария в текстах.

6. Используйте ИИ для ускоренного составления определений.

7. Регулярно поддерживайте и обновляйте глоссарий.

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

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

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