Взять займ
Как создать глоссарий для ИТ‑документации
Привет! Мы — команда документирования Platform. Хотим по‑человечески рассказать, как мы мучились с терминами, что перепробовали и как в итоге сделали толковый глоссарий. Может, наш опыт сэкономит вам кучу времени.
С чего всё началось
В ИТ полно терминов на английском, которые либо не переводятся, либо переводятся по‑разному. Из‑за этого в документации начиналась путаница: одно и то же слово писали то латиницей, то кириллицей, то вообще по‑разному. Нам нужно было навести порядок — и не просто пару слов поправить, а разобраться с сотнями терминов из кибербезопасности, работы с данными, интеграции и прочего.
Первые попытки и первые ошибки
Сначала мы просто собрали все термины из документации вручную: взяли старые глоссарии, попытались дать единые определения. Но быстро поняли, что это не работает:
одни и те же слова писали по‑разному;
не было чётких правил, какие слова включать;
когда начали делить термины на категории («общие», «специфичные»), стало ещё запутаннее.
Получилось несколько кусков глоссария без общей логики — и мы решили всё переосмыслить.
Что мы выяснили, когда копнули глубже
Посмотрели, как делают другие (например, в Cloud Native), поговорили с переводчиками и локализаторами, изучили опыт Госуслуг. И нашли главные проблемы:
непонятно, для кого глоссарий;
нет критериев отбора терминов;
никто не решал, какой вариант написания считать правильным;
обновлять такой глоссарий было нереально сложно.
Наш рабочий подход: два этапа
Мы разделили работу на две большие части:
Собрать и обработать список терминов.
Написать понятные определения.
Этап 1. Отбираем термины
Сначала задали себе простые вопросы:
Кому это нужно?
Кто будет пользоваться глоссарием?
Какие слова точно считать терминами?
Целевая аудитория — программисты, инженеры, архитекторы ПО, специалисты по ИБ. То есть люди, которые в теме, но им нужно единое написание слов.
Как собирали термины: взяли инструмент для автоматического поиска ключевых слов в текстах. Он учитывал:
частоту (если слово встречается меньше пяти раз — пропускаем);
значимость (оценивал, насколько слово важно для текста);
длину (брали фразы из 1–3 слов);
контекст (выявлял устойчивые сочетания);
морфологию (приводил слова к начальной форме).
Ещё доработали инструмент, чтобы он группировал термины по продуктам, версиям и документам. Это сильно помогло.
После того как убрали дубликаты, осталось 23 311 потенциальных терминов. Потом мы их отсеяли до 213 — самых проблемных: те, что вызывают сложности с написанием или требуют чёткого определения.
Структура глоссария
Для каждого термина завели карточку с полями:
Термин — то, что мы отобрали.
Упоминания — все варианты написания, которые встречались.
Используем — правильный вариант.
Аналог — допустимый альтернативный вариант (но не синоним: в одном документе используем только один вариант).
На англ. яз. — оригинал, если он важен (например, для кода).
Не используем — «чёрные списки» неправильных вариантов.
Латиница или кириллица?
Один из главных вопросов: писать слово на английском или переводить? Мы решили так:
если слово встречается на кириллице и латинице примерно одинаково часто — выбираем кириллицу;
следуем правилам русского языка, чтобы текст оставался читаемым.
Например, слово «веб» уже прижилось и пишется кириллицей. А вот «backend» пока лучше оставить на английском — иначе не получится добавить русские окончания без потери читаемости.
Этап 2. Пишем определения
Просто собрать термины мало — нужно объяснить, что они значат. Делать это вручную заняло бы полгода‑год, поэтому мы пошли хитрее:
использовали ИИ (GigaChat от Сбера) для генерации первых версий определений;
эксперты из команды проверяли и правили эти определения;
выбирали лучший вариант из нескольких предложенных.
Пример для термина «бэкап»: (backup)= Бэкап
Сохранение копии данных на локальном или удалённом носителе.
Пример употребления: перед обновлением продукта рекомендуется сделать бэкап базы данных.
Допустимые аналоги: резервное копирование.
Нерекомендуемые синонимы: бекап, backup, бекапить.
Как поддерживали порядок
Чтобы термины не расползались по документам, сделали автоматизированные проверки:
встроили их в Platform V GetDocs — наш инструмент для документации;
при сборке документации система выдаёт отчёт: где использованы слова не по глоссарию;
например, если в тексте написано «node», а в глоссарии закреплён вариант «узел», система это отметит.
Финальная вычитка и обратная связь
выложили первую версию на публичную страницу — за две недели собрали отзывы;
обсуждали спорные моменты в рабочей группе (не больше 8 человек, чтобы не было хаоса);
если не могли договориться — проводили опросы в чатах;
после утверждения залили глоссарий в репозиторий, а правки принимаем через pull request.
Сколько времени это заняло?
сбор терминов и настройка инструмента — около двух дней;
анализ и создание словарных статей — примерно год (параллельно с другими задачами);
сейчас в глоссарии более 500 терминов, добавляем 5–10 новых ежемесячно.
Наши советы для тех, кто хочет сделать свой глоссарий
Определите аудиторию. Для кого этот глоссарий?
Соберите тексты. Чем больше материала, тем точнее отбор.
Автоматизируйте сбор терминов. Не делайте всё вручную.
Продумайте структуру. Чёткие поля (термин, правильное написание, запрещённые варианты и т. д.) упростят работу.
Настройте автоматические проверки. Пусть система сама отмечает ошибки.
Используйте ИИ. Он ускорит создание определений.
Обновляйте глоссарий. Язык меняется — термины тоже.
Итог
Наш глоссарий помог сделать документацию Platform V чёткой и единообразной. Это не волшебная таблетка — он требует внимания и обновлений, но результат того стоит.
А как вы работаете с терминологией? Делитесь в комментариях: какие подходы используете, с какими проблемами сталкивались, какие лайфхаки знаете. Будем рады обсудить!
P.S. Огромное спасибо всем, кто участвовал в разработке глоссария. Это действительно огромный труд — и он того стоил!
Читайте также: Что такое СТМ и с чего всё начиналось • Погружаемся в мир IT‑терминов
Комментарии (0)