Единый источник

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

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

Примеры

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

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

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

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

Способ применяется, если общего контента больше, чем уникального.

Переиспользование контента позволяет подставлять повторяющиеся фрагменты текста внутри одного или нескольких документов.

Способ применяется, если уникального контента больше, чем общего.

Переиспользование обеспечивают:

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

  Пример

  В справке Яндекс Музыки некоторые разделы содержат повторяющуюся информацию. Такие блоки оформляются в виде инклюдов и включаются в нужные места текста. Например, Дополнительные преимущества в сервисах Яндекса и Что входит в подписку Плюса.

• Пресеты переменных — набор переменных и их значений. При сборке документа в текст подставляется значение переменной в зависимости от условий сборки.

  Пример

  В справке Яндекс Почты переменная действие_с_письмом может иметь разные значения:

  • для мобильного приложения — «Нажмите значок в правом нижнем углу экрана»;
  • для веб-версии — «Чтобы создать новое письмо, в левом верхнем углу экрана нажмите „Написать“».

• Вставки оглавлений — блоки оглавления, которые вставляются в основное оглавление.

  Пример

  В справке Яндекс Почты основная справка содержит несколько крупных разделов, например, «Управление контактами», «Настройка почтового ящика». Для каждого раздела создается свой блок оглавления, который включает подразделы и ключевые темы. С помощью вставок оглавлений эти блоки включаются в общее оглавление справки, что позволяет пользователям быстро находить нужные разделы и ориентироваться в большом объеме информации.

Особенности

• Каталоги с изображениями и инклюдами рекомендуется размещать в папках с названием _assets и _includes соответственно. Символ _ означает, что папка не будет отображаться в итоговой сборке, но может быть использована как источник.

• Внутри проекта с профилированием можно дополнительно использовать инклюды или пресеты переменных, поэтому способы можно комбинировать.

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

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