Меня зовут Диана, я технический писатель-аналитик в Контуре 👋

Каждый из нас когда-то попадал в новую компанию людей. Помните это ощущение: вроде говорите на одном языке, а понимаете только часть историй. Они шутят или вспоминают общего знакомого, а для вас образы не рисуются, из-за чего сложно уловить посыл или общую эмоцию. Всё это очень просто объясняется: у вас с компанией не накопился общий контекст. Эти люди давно общаются, многое пережили вместе, имеют общих знакомых. Вы действительно говорите на одном языке, но эта группа успела сформировать свой шифр, и при разговоре вкладывает в знакомые всем слова свои воспоминания и значения. Мозг в этой ситуации делает понятный вывод: чтобы освоиться, надо перенять контекст. Вы начинаете задавать вопросы, новые друзья делают в историях пояснения, и вот спустя полгода вы наконец породнились. А как бы всё ускорилось, если бы в самом начале вам выдали расшифровки 🙂

Отсутствие общего контекста — первая проблема, с которой мы сталкиваемся и в профессиональной среде. Приходим на новую работу, изучаем новый продукт, хотим разобраться с новым сервисом — везде встречаемся с терминами, которые понимаем по-своему или слышим впервые. Здесь тоже можно пойти по пути, который описан выше, и задавать коллегам вопросы. Но устно передавать информацию слишком долго и дорого, в IT нужно более практичное решение. В этой статье поговорим о том, как создать глоссарий, который поможет читателю подружиться с документацией, а команде — быстро и дёшево передавать контекст.

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

Почему глоссарий нужен или какие проблемы он решает

Частые явления в документации, которые мешают восприятию информации:

Псевдосинонимы

Пример: подпись, сертификат, ключ

Одна и та же сущность в рамках одной страницы описана разными словами. Иногда хочется заменить слово синонимичным понятием, чтобы избежать повторений, но для технической документации это спорное решение. Понятия из примера технически и юридически имеют разные смыслы. Читатель не должен каждый раз останавливаться и думать: «А это то же самое, что было выше, или другое?».

Обилие аббревиатур

Пример: ЛПР выпустил ЭЦП для ЭДО его ЮЛ

Лицо, принимающее решение, выпустил электронную цифровую подпись для электронного документооборота его юридического лица

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

Рассинхрон смыслов

Пример: пользователь

В одном документе «пользователем» называют человека, а в другом — техническую сущность в базе данных. Читатель в таких ситуациях тратит больше времени на поиск правды или понимает часть информации неверно.

Знакомое слово в незнакомом значении

Пример: в Контур.Диадоке есть роуминг, а в Контур.Экстерне — ИОН

Роуминг в Диадоке — это технология документооборота между разными операторами ЭДО. Не имеет общего с ограничениями мобильной связи за рубежом.

ИОН в Экстерне — информационное обслуживание налогоплательщика, а не электрически заряженная частица.

Функции сервиса могут называться словами, которые в широком смысле имеют другое значение. Если не дать читателю расшифровку термина в контексте продукта, то в его голове возникнет только путаница.

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

Именно поэтому глоссарий — это способ уменьшить путаницу, ускорить онбординг и работу команды, повысить доверие к документации и снизить количество ошибок в коммуникации.

Какие бывают глоссарии

Кратко выделим три формата.

Словарь

Содержит 2 поля: термин и его определение. Может быть развернут на одной странице списком или разделен на подстраницы для сортировки по темам или алфавиту.

Список сокращений

Похож на словарь, отличается только ориентированностью на аббревиатуры и сокращения.

Тезаурус

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

Выбор формата для глоссария будет зависеть от накопленного контекста, сложности продукта и ресурсов команды. Главная сила первых двух вариантов — это краткость: читатель может бегло ознакомиться с понятием. Ещё один приятный плюс: они достаточно просты и интуитивно понятны в реализации. Мы не будем на них задерживаться. Формат тезауруса более сложный в реализации, но и эффект от него более продолжительный: читатель получает систему знаний. Далее подробнее раскроем глоссарий именно через тезаурус.

Как создать свой эффективный глоссарий

Подготовительный шаг в создании глоссария — отобрать ключевые термины. Для начала их может быть всего 5-10. Не стоит гнаться за количеством, для старта важнее внести ясность в самые часто встречающиеся понятия внутри продукта.

Далее описываем формулу для наполнения каждой страницы с термином:

1. Сформулируйте определение в 1-2 предложениях

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

2. Укажите допустимые и недопустимые синонимы — опционально

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

Оптимальнее всего идти по правилу «Один термин = один смысл». Чтобы оставаться в разумных рамках, рекомендуем выделить один термин, как главный, а дополнительные только упомянуть в формате «Также называют», «Могут называть», «Разговорный синоним» и больше не использовать их в текстах. Недопустимые синонимы можно оформить в подразделе «Не путать с».

3. Опишите связь термина с другими сущностями в продукте

В каком сценарии встречается термин? Какие явления с ним связаны? Из каких других терминов состоит? В этом разделе формируем в голове читателя пространственные связи внутри продукта.

4. Раскройте термин через рабочие инструменты и ресурсы

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

5. Постройте путь к связанным страницам документации

Добавьте блок ссылок на:

  • Инструкции по работе с термином

  • Сценарии работы с термином

  • Методы работы с термином

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

6. Расставьте везде гиперссылки на страницы с терминами

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

Чтобы текст не превратился в сплошные синие ссылки, введите простые правила:

  • Навешивайте ссылку только при первом упоминании термина на странице.

  • В словосочетании из терминов выделяйте только ключевое слово, а не все подряд. Пример: администратор организации.

В дальнейшем для развития и поддержания глоссария действуйте стандартно: регулярно проверяйте актуальность, корректируйте, дополняйте, при необходимости вводите новые термины. Вы превосходны!

Как это выглядит на практике

Недавно команда технических писателей-аналитиков Диадока ввела Глоссарий в документацию API Диадока. Поговорим об этом опыте.

Кратко о процессе:

  • Работали по описанным выше шагам.

  • Создали образец страницы термина, чтобы вести глоссарий единообразно.

  • Скомпоновали термины и их родственные понятия на одной странице.

  • Каждую страницу провели через ревью аналитиков и экспертов команды.

Кратко об итогах:

  • Сейчас глоссарий содержит 24 страницы и раскрывает суть 30+ терминов. Базовый минимум точно закрыт.

  • Команда оперативно добавляет новые страницы, теперь это часть процесса.

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

  • Глоссарий стал одной из точек навигации.

  • Пользователи довольны.

Кратко о планах:

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

  • Двигаться к роскошному максимуму — поддерживать имеющееся, дополнять новым при необходимости.

Заключение

Как итог, благодаря глоссарию вы получите следующие бонусы:

  • Текст документации короче — избавитесь от разносортных синонимов, повысите точность терминологии.

  • Двусмысленности меньше — для каждого термина будет сформулирован один смысл, доступный для всех.

  • Стилистика текста единообразнее — все писатели документации будут ориентироваться на выверенный список терминов.

  • Ошибок и разночтений меньше — не нужно будет интерпретировать термин по-своему.

  • Онбординг быстрее — станет меньше препятствий для погружения в контекст.

  • Коммуникация между коллегами проще — глоссарий поможет поддержке, разработке и менеджерам говорить на одном языке.