В восьми руководствах одно и то же предупреждение об опасном напряжении. Юридический отдел меняет формулировку. Технический писатель открывает восемь документов, ищет нужный абзац в каждом, правит. В одном пропустил. Через месяц это находит аудитор.
Эту проблему решают фрагменты контента — переиспользуемые блоки текста, которые хранятся в одном месте и автоматически подставляются во все документы, где нужны. Обновил источник — обновилось везде. Восемь документов, одна правка, ноль расхождений.
Коротко о термине: в SEO «фрагментом контента» или «сниппетом» называют выдержку из страницы в поисковой выдаче, в программировании — фрагмент кода (React fragment, Document Fragment). В технической документации смысл другой.
Что такое фрагмент контента в документации
Фрагмент контента (content fragment, сниппет) в технической документации — это блок текста, таблицы, списка или другого форматированного контента, который создаётся один раз и вставляется по ссылке в любое количество страниц или документов. При изменении исходного фрагмента все вхождения обновляются автоматически. Автор работает не с набором независимых копий, а с системой связанных материалов, где каждое изменение проходит через один источник.
Это один из трёх основных инструментов повторного использования контента — наряду с переменными и условным контентом. Чтобы понять где именно применяется каждый из них, полезно сразу разграничить их между собой.
Сниппеты часто путают с переменными. Это разные инструменты. Переменная хранит одно короткое значение без форматирования: название продукта, номер версии, телефон поддержки. Фрагмент контента — блок форматированного контента любого размера: от одного предупреждения до нескольких страниц с изображениями, таблицами и списками. Переменная полезна там, где меняется одно значение, но структура остаётся прежней. Фрагмент — там, где важны и структура, и оформление, и идентичность текста в нескольких местах.
| Критерий | Переменная | Фрагмент контента (сниппет) |
| Что хранит | Слово, фразу, число | Абзац, таблицу, раздел с форматированием |
| Размер | Одна строка | Любой — от фразы до страницы |
| Форматирование | Нет | Полное HTML-форматирование |
| Типичные примеры | Название продукта, версия, дата релиза | Предупреждение, инструкция по установке, политика |
| Обновление | Мгновенно везде | Мгновенно везде |
Переменная — это данные (одно значение без оформления). Фрагмент — это контент (структурированный блок, который живёт как самостоятельная единица). Они хорошо работают вместе: переменная подставляет название продукта внутри фрагмента, а сам фрагмент включается в десятки страниц.
Где применяется: типичные кандидаты на фрагментизацию
Главный критерий — контент повторяется в трёх и более документах и должен быть идентичным. Вот наиболее частые сценарии.
Предупреждения и предостережения. Стандартные предупреждения об опасности, юридические оговорки, предостережения по безопасности. Любое расхождение в формулировке может изменить юридический смысл или создать риск для пользователя — идеальный кандидат.
Системные требования. Раздел «Требования к системе» одинаков в руководстве пользователя, руководстве по установке и техническом описании. Три документа, один источник.
Процедуры установки и начальной настройки. Шаги установки повторяются в быстром старте (QSG), полном руководстве и FAQ. Вместо трёх почти одинаковых описаний — один фрагмент в трёх местах.
Контактная информация и юридический текст. Телефоны поддержки, адреса, политики конфиденциальности, лицензионные оговорки меняются централизованно. Ручной поиск по всему порталу при каждом обновлении — лишняя работа.
Повторяющиеся разделы в похожих продуктах. Линейка из пяти приборов с одинаковым разделом «Техническое обслуживание»: один фрагмент вставляется в пять руководств. Обновление для всей линейки — одна правка.
Глоссарий и определения терминов. Определение термина, используемое в нескольких документах, хранится как фрагмент — единое определение без расхождений. Особенно важно, когда термин встречается и в справке, и в руководстве, и в политике продукта.
Как это работает: механика
Принцип «страница-сниппет»
В большинстве систем документации фрагмент контента — это обычная страница или топик, помеченная как источник для повторного использования. Она не отображается в навигации и не публикуется как самостоятельная страница, но её содержимое вставляется в другие страницы по ссылке.
Вставка по ссылке
Когда техрайтер вставляет фрагмент в страницу, он не копирует текст — он вставляет ссылку на страницу-источник. В редакторе видно, что это фрагмент (обычно выделен рамкой или иконкой). В опубликованной версии читатель видит просто текст.
Хорошая аналогия — режим «Связать с файлом» при вставке изображения в Word. Документ хранит не само изображение, а путь к нему: при открытии файл подгружается заново. Если исходник изменился — изображение в документе обновится при следующем открытии. Сниппет работает так же: документ хранит не текст, а ссылку на страницу-источник; при публикации система подгружает актуальное содержимое.
Обновление
Изменилось содержимое страницы-источника — при следующей публикации все страницы, использующие этот фрагмент, получат обновлённый контент автоматически. Вместо последовательной правки в десятках мест — одно изменение в исходнике. Особенно ценно, когда текст связан с безопасностью, правовыми оговорками или сертификационными требованиями: цена пропущенного обновления высока.
Как организовать библиотеку фрагментов
Десять сниппетов — удобно. Сто сниппетов без системы — беспорядок. По мере роста библиотеки главной задачей становится управление фрагментами, а не их создание.
Понятные имена. Название фрагмента должно объяснять, что внутри: «Предупреждение_электробезопасность» лучше, чем «Сниппет_12». Через год коллега не будет угадывать содержимое.
Описание назначения. К каждому фрагменту — короткое описание: что содержит, в каких документах используется, кто владелец. Это документация на документацию.
Структура хранения. Фрагменты лучше хранить в отдельном разделе или папке, отделённой от обычных страниц. В Документерре страницы-сниппеты скрываются из дерева страниц — они доступны авторам, но не перегружают навигацию портала.
Аудит использования. Периодически проверяйте: какие фрагменты используются, какие устарели, какие созданы «на всякий случай» и нигде не вставлены. Неиспользуемый фрагмент — потенциальный источник путаницы.
Владелец фрагмента. Для каждого фрагмента — конкретный ответственный, не «все». Без владельца фрагменты устаревают молча.
Типичные ошибки
Делать фрагменты из всего подряд. Фрагмент оправдан, когда контент реально повторяется в нескольких местах и должен быть идентичным. Уникальный текст, который встречается один раз, фрагментировать не нужно — это усложнение без пользы.
Слишком большой фрагмент. Если фрагмент на 80% подходит для контекста, но требует правки при каждом использовании — это не кандидат для фрагмента. Хороший фрагмент вставляется без изменений. Иначе он начинает работать как проблема, а не как решение.
Не документировать библиотеку. Через полгода никто не помнит, какой фрагмент для чего создан. Команда дублирует уже существующий контент или создаёт новые версии того же текста. Итог — библиотека, в которой трудно разобраться даже её автору.
Вставлять редактируемые копии. Некоторые инструменты позволяют вставить фрагмент как локальную копию — она больше не обновляется при изменении источника. Использовать осторожно: только когда вариация действительно нужна для конкретного контекста.
Менять фрагменты без согласования. Когда несколько человек редактируют один источник без регламента, вероятность случайного несоответствия растёт. Библиотека фрагментов должна существовать не только как набор страниц, но и как процесс управления содержанием.
Размещать контекстные навигационные элементы внутри сниппетов. Хлебные крошки, ссылки «Следующая/Предыдущая страница» и блоки «Связанные статьи» вычисляются относительно страницы, в которой они физически размещены. Если разместить такой элемент внутри сниппета, навигация будет рассчитываться относительно страницы-источника, а не страницы-приёмника. Результат окажется неверным. Контекстные навигационные элементы размещают в Master Page или непосредственно в теле целевой страницы.
Фрагменты контента в Документерре
В Документерре фрагменты контента реализованы как сниппеты. Механика строится на концепции страницы-сниппета: создаётся обычная страница с контентом для повторного использования, затем она вставляется в другие страницы по ссылке.
Два способа создать сниппет:
- Написать контент заранее → создать отдельную страницу → вставить её через «Вставка» → «Единый источник» → «Вставить сниппет».
- Выделить уже написанный текст → нажать «Создать сниппет» — система автоматически создаст страницу-источник и заменит выделенный фрагмент ссылкой на неё. Удобно, когда потребность в повторном использовании стала очевидна уже после написания текста.
При создании через второй способ Документерра автоматически скрывает страницу-сниппет из дерева страниц и не публикует её как самостоятельную страницу. Контент остаётся доступным для авторов, но не засоряет навигацию портала.
Как вставить сниппет:
Через «Вставка» → «Единый источник» → «Вставить сниппет» — начните вводить имя страницы или её ID, выберите из списка, нажмите «Вставить». В режиме редактирования сниппет отображается как именованный блок. В публикации — как обычный контент без видимых следов механизма.
Динамические элементы и сниппеты:
Контекстные навигационные элементы в Документерре (хлебные крошки, ссылки «Следующая/Предыдущая страница», блоки «Связанные статьи») вычисляются относительно страницы, в которой они физически размещены. Если вставить такой элемент внутрь сниппета, навигация будет рассчитываться относительно страницы-источника сниппета, а не страницы-приёмника. Поэтому контекстные навигационные элементы размещают в Master Page или непосредственно в теле целевой страницы — не внутри сниппетов.
Для тонкой настройки сниппеты можно добавлять через HTML-атрибут ch:snippet-src с указанием URL страницы-источника.
Инструменты повторного использования контента в Документерре:
- Сниппеты — переиспользуемые блоки форматированного контента: от одного предупреждения до целого раздела. Описаны в этой статье.
- Переменные — короткие подставляемые значения без форматирования: название продукта, номер версии, контактные данные. Обновляются централизованно и мгновенно распространяются по всем документам.
- Условный контент — механизм включения и исключения фрагментов в зависимости от аудитории, версии продукта или формата публикации. Один проект, разные публикации.
Все три инструмента работают вместе: переменная подставляет название продукта внутри сниппета, а сниппет включается в нужные страницы только для определённой аудитории через условный контент.
* * *
Фрагменты контента — прямой ответ на вопрос «как не писать одно и то же дважды». Они работают там, где контент должен быть буквально идентичным в нескольких местах: предупреждения, процедуры, политики, системные требования. В масштабной документации именно такие блоки создают наибольшую нагрузку при ручной поддержке.
ЧаВо
Шаблон задаёт структуру нового документа при его создании — заголовки, разделы, типовые блоки. После создания страница становится самостоятельной и никак не связана с шаблоном. Сниппет — живая связь: изменение источника мгновенно отражается во всех вхождениях. Шаблон отвечает на вопрос «как начать», сниппет — «как поддерживать идентичность».
Технически в большинстве систем — да, это называется вложенными сниппетами. Но использовать осторожно: вложенность усложняет отладку и делает зависимости непрозрачными. Если вы не можете быстро объяснить коллеге, какой сниппет откуда берётся — структура уже слишком сложная.
Простое правило: если один и тот же блок встречается в трёх и более местах и должен быть идентичным — это кандидат на фрагментизацию. Если блок встречается дважды с небольшими вариациями — скорее всего, это разный контент, не стоит его искусственно унифицировать.
Все вхождения становятся битыми ссылками — читатель увидит пустое место или ошибку. В Документерре система предупреждает об использованиях страницы перед удалением. Перед удалением источника всегда проверяйте, где он используется.
Да, особенно для юридических текстов, предупреждений и политик. Поскольку изменение одного источника затрагивает сразу все документы, случайная правка может создать проблему в десятках мест одновременно. Для критичных фрагментов рекомендуется процесс рецензирования перед публикацией.
Фрагмент-источник локализуется один раз — переведённая версия подставляется во все вхождения. Это одно из главных преимуществ: переводчик правит в одном месте, а не ищет повторяющийся блок по всем документам. При этом важно убедиться, что в локализованных версиях используется именно переведённый источник, а не исходный.
Нет. Сниппет оправдан там, где повторное использование уже есть, а не там, где оно предполагается. «Запасные» фрагменты без реальных вхождений засоряют библиотеку и создают путаницу при аудите.
