Техрайтер ведёт два руководства — для базовой версии продукта и для профессиональной. Документация на 85% одинаковая. Когда меняется общий раздел, правку вносят в двух местах. Иногда забывают обновить одно из них. Клиент находит расхождение.
Или другой сценарий: одно руководство нужно выпустить онлайн и в PDF. В онлайне — видео и интерактивные подсказки. В PDF это либо не работает, либо выглядит странно. Значит, перед каждым экспортом придётся вручную чистить одно и то же.
Условный контент решает оба случая: один исходный проект, разные выходы — в зависимости от аудитории, версии продукта или формата публикации. В этой статье разберём, как работает этот механизм, когда он нужен и как внедрить его с нуля.
Что такое условный контент
Условный контент (conditional content) — фрагменты документации, которые включаются или исключаются из публикации в зависимости от заданных условий. Условием может быть роль пользователя, версия продукта, формат вывода, язык или любой другой параметр, который задаёт технический писатель.
Исходный документ содержит весь материал целиком. Отдельные фрагменты помечаются тегами, а система управления документацией фильтрует их по активным условиям при публикации. В один выход попадает один набор блоков, в другой — другой. Источник остаётся единым — это и есть принцип single-sourcing, публикация из единого источника.
Условный контент — один из трёх основных инструментов повторного использования контента.
- Переменные отвечают за «одно значение — много мест». Например, название продукта или номер версии: меняете в одном месте — обновляется везде сразу.
- Сниппеты — за «один блок — много документов». Например, раздел «Системные требования», который используется в пяти руководствах: редактируете один раз — меняется во всех.
- Условный контент — за «один документ — много аудиторий».
Все три инструмента хорошо работают вместе.
Ключевой эффект: в документации появляется один «источник правды», и исчезает риск того, что несколько похожих текстов постепенно расходятся из-за несинхронизированных правок.
Когда нужен условный контент: типичные сценарии
Несколько версий или тарифов продукта
Самый частый сценарий — продукт с несколькими версиями или тарифными планами. В базовой подписке функции ограничены, в профессиональной доступны дополнительные сценарии, интеграции и настройки.
Без условного контента техрайтер дублирует общую часть из версии в версию вручную, а различия правит в каждом документе отдельно. С условным контентом общий текст хранится в одном месте, а специфичные блоки включаются только там, где нужны. Особенно удобно для SaaS-сервисов, где Free, Growth и Enterprise отличаются не всей документацией, а несколькими разделами.
Разные роли пользователей
Конечному пользователю нужны рабочие сценарии. Администратору — права доступа, системные параметры, политики безопасности. Если объединить всё в одном документе, пользователь получит избыточный объём, а администратор потратит время на поиск нужного.
Условный контент решает это без двух отдельных руководств. Пользовательская версия остаётся короткой, административная — полной. Каждая аудитория видит ровно тот уровень глубины, который ей нужен.
Разные форматы вывода
Онлайн-версия и PDF живут по разным правилам. В онлайне работают видео, выпадающие блоки, встроенные элементы, переходы по ссылкам. В PDF важны статичность, компактность и линейная структура.
В формате PDF важны другие характеристики: статичность, неизменяемость, компактность и линейная структура. Если не использовать условный контент, техническому писателю приходится вручную убирать неподходящие элементы или вести две версии материала.
Вместо того чтобы поддерживать два документа, видеоблоки помечаются тегом «только онлайн» и автоматически исключаются из PDF. Вместо них можно условно подставить статичный скриншот с подписью. Это особенно важно, когда PDF нужен как официальный документ для печати, согласования или архива.
Несколько похожих продуктов
Линейка из нескольких продуктов, которые отличаются отдельными функциями. Это могут быть модели оборудования, редакции платформы или пакеты для разных сегментов рынка. Когда 80% документации совпадает, поддерживать их по отдельности неэффективно.
Условный контент держит общие разделы в одном месте, а специфичные блоки выносит в условные фрагменты. Для техрайтера это меньше копий и меньше мест, где нужно вносить одну и ту же правку.
Как это работает: механика условного контента
Теги (условные метки)
Основа механизма — теги. Техрайтер заранее задаёт набор тегов, отражающих сценарии публикации: например, AdminOnly, ProVersion, OnlineOnly, PrintedDoc. Фрагменты текста связываются с этими тегами, и при публикации система понимает, что именно должно войти в конкретный выход.
Теги должны быть не только технически корректными, но и понятными. Если название не объясняет, зачем тег нужен, через несколько месяцев проектом будет сложно пользоваться даже его автору. Хорошая система тегов начинается с ясной номенклатуры, коротких описаний и единых правил использования для всей команды.
Включение и исключение
Два типа логики:
- Включение — блок появляется в публикации, только если нужный тег активен. Всё остальное скрыто.
- Исключение — блок скрывается, если тег активен. Всё остальное показывается.
Фильтрация товаров на маркетплейсе работает по тому же принципу, что и условный контент в документации
Если у контента много общего и мало различий, удобнее строить схему вокруг исключений. Если большинство блоков зависит от аудитории или версии — удобнее включения. Главное — не смешивать подходы бессистемно: тогда структура становится запутанной и её тяжело поддерживать.
Что может быть условным
Условным может быть почти любой уровень: отдельная фраза внутри предложения, абзац, предупреждение, таблица, шаг процедуры, раздел, целая страница или пункт в оглавлении. Чем выше уровень условия, тем проще управление, но тем меньше гибкости для тонкой настройки.
На уровне фразы удобно менять термин или короткую оговорку. На уровне абзаца — адаптировать пояснение под аудиторию. На уровне главы — показывать целиком разные сценарии, когда различия между версиями уже заметны, но общая структура документа ещё сохраняется.
Предпросмотр
Хороший инструмент даёт возможность выбрать нужные теги и увидеть, как будет выглядеть документ после публикации — до генерации. Ошибки в условиях редко заметны сразу: нужный блок может исчезнуть или появиться не в том варианте. Без регулярного предпросмотра условный контент становится источником скрытых дефектов.
Типичные ошибки
- Слишком много тегов
Когда условий накапливается слишком много, система теряет прозрачность: авторы перестают понимать, что и где используется, а публикация требует постоянной ручной проверки. Начинайте с минимального набора и расширяйте только под реальную потребность. Простой ориентир: если новый тег нельзя объяснить одной короткой фразой — система уже разрастается быстрее, чем нужно.
- Теги без описаний
Через несколько месяцев тег Version_B_Legacy_2023 выглядит как набор слов без контекста. Без описаний проект теряет воспроизводимость: новые авторы вынуждены угадывать логику. Реестр тегов — это документация на саму документацию. Он нужен не для формальности, а чтобы условная логика оставалась понятной при смене людей в команде.
- Условный контент вместо отдельного документа
Если два продукта различаются слишком сильно, условные блоки начнут мешать больше, чем помогать. Условный контент работает там, где общего материала значительно больше, чем различий. Когда различий становится больше половины — лучше разделить проекты.
- Проверяется только «основная» версия
Добавили новый блок, не назначили тег — он появился у не той аудитории. Или важный фрагмент исчез, потому что условие сработало неожиданно. Тестировать нужно все варианты публикации, а не только самый очевидный.
- Нет дефолтного поведения
Если условие не сработало, читатель может увидеть пустое место, рваный текст или шаг процедуры без пояснения. Для каждой условной части нужно заранее понимать, что увидит пользователь, когда условие не выполнено: нейтральный текст, общий абзац или статичный элемент вместо интерактивного.
Условный контент в Документерре
В Документерре механизм построен на тегах публикации (Условные теги). Сначала они создаются в настройках проекта, затем применяются к нужным фрагментам через раздел «Единый источник» на вкладке «Вставка». При публикации или предпросмотре выбирается активный набор тегов, и система собирает нужный вариант документа.
В интерфейсе три базовые операции:
- «Вставить условный блок» — создаёт новый условный фрагмент в позиции курсора. Тип условия (включение или исключение) выбирается сразу.
- «Сделать условным» — превращает уже существующий контент в условный без пересоздания. Удобно при работе с уже написанной документацией.
- «Очистить условия» — снимает теги и возвращает элемент в безусловный вид. Контент при этом не удаляется.
Поддерживаются два типа условий: include показывает фрагмент только при активном теге, exclude скрывает его при активном теге. Для тонкой настройки условия можно задавать напрямую в HTML через атрибуты ch:include или ch:exclude — это удобно при нестандартных структурах и автоматизации.
После разметки можно переключиться в режим предпросмотра, выбрать нужные теги и увидеть итоговый вид публикации до генерации. Это снижает риск пропущенных ошибок и позволяет проверить все варианты до релиза.
Как начать
Шаг 1. Определите сценарий. Начинайте не с тегов, а с задачи. Ответьте на вопрос: зачем именно нужен условный контент — разные версии продукта, разные роли, разные форматы? Один чёткий сценарий даст понимание, на каком уровне нужны условия: блок, раздел, страница или вся публикация.
Шаг 2. Спроектируйте систему тегов. Создайте минимальный набор с короткими, однозначными именами. Зафиксируйте отдельно: когда тег применяется и кто отвечает за его использование. Реестр тегов — это первое, что поможет новому автору войти в проект без лишних вопросов.
Шаг 3. Начните с одного документа. Возьмите руководство, которое уже ведётся в нескольких копиях или должно выходить в двух вариантах. На одном документе проще оценить, насколько подход подходит вашей команде, чем на большом и сложном проекте.
Шаг 4. Проверьте все варианты. Перед публикацией включите предпросмотр для каждой комбинации тегов. Чем больше форматов и каналов, тем выше цена случайной ошибки.
Шаг 5. Масштабируйте постепенно. Сначала один проект, затем похожие руководства, потом сценарии с несколькими ролями и форматами. Попытка условно разметить всю документацию сразу почти всегда заканчивается хаосом.
* * *
Условный контент — способ вести один проект вместо нескольких почти одинаковых копий. Техрайтер пишет один раз, система собирает нужные фрагменты для каждой аудитории, версии и формата. Наибольшую отдачу это даёт там, где много общих блоков и высокая цена расхождений между версиями.
Эффективность зависит от дисциплины: минимальный понятный набор тегов, задокументированные правила, регулярный предпросмотр и трезвая оценка того, когда условный контент действительно оправдан, а когда лучше сделать отдельный документ.
Один источник правды — разные публикации без дублирования.
ЧаВо
Сниппет — это готовый блок контента, который вставляется в несколько документов. Он всегда отображается там, где вставлен. Условный контент — это логика показа: один и тот же фрагмент в одном документе появляется у одной аудитории и скрывается у другой. Сниппеты отвечают на вопрос «где использовать этот блок», условный контент — «кому его показывать».
Да. В Документерре для этого есть операция «Сделать условным» — она превращает уже написанный фрагмент в условный без пересоздания. Удобнее всего начинать с одного документа, который существует в нескольких копиях: это даёт быстрый и наглядный результат.
Зависит от типа условия. При включении (include) фрагмент просто не попадает в публикацию — читатель его не видит. При исключении (exclude) фрагмент появляется, когда тег неактивен. Важно заранее продумать, что увидит пользователь, если условие не сработало: пустое место или рваный текст — это ошибка проектирования, не инструмента.
Когда различий больше, чем общего. Хороший ориентир — если два варианта документации расходятся более чем на 40–50%, поддерживать их в одном проекте через условные блоки становится труднее, чем вести раздельно. Другой сигнал: если логика тегов требует длинного объяснения, чтобы новый автор понял, что куда включать, — скорее всего, проект стал слишком сложным.
Не обязательно после каждого, но регулярно — да. Достаточно проверять предпросмотр всех вариантов перед каждым релизом. Если документация обновляется часто, полезно завести чеклист: список комбинаций тегов, которые нужно просмотреть перед публикацией.
Можно, но осторожно. Смешивать оба подхода без системы — частая причина путаницы. Лучше выбрать одну логику как основную и придерживаться её. Переключаться на второй подход стоит только там, где первый явно неудобен, и фиксировать это в реестре тегов как исключение из правила.
