Основные понятия
В этом разделе рассматриваются основные понятия, используемые в системе Документерра, и то, как они связаны друг с другом.
Портал документации
Это понятие относится ко всему веб-приложению, которое вы получаете при использовании системы Документерра.
Каждый портал документации имеет уникальный адрес, который выглядит следующим образом: portal-name.documenterra.co.
Портал документации — это единая площадка, где технические писатели могут работать над контентом, а клиенты — читать руководства пользователя. Благодаря архитектуре Документерры авторы могут создавать новые материалы, не затрагивая контент, который видят читатели.
Проект
Чтобы начать разработку нового руководства пользователя, необходимо создать новый проект. Все созданные страницы справки хранятся в проекте. Проекты используются только для разработки документации. Они не предназначены для предоставления доступа читателям. Проекты видны только авторизованным пользователям после входа на портал документации.
Шаблон проекта
При создании нового проекта можно выбрать любой шаблон проекта и получить готовый дизайн. Стили, изображения, фоны и цвета являются составными частями шаблона проекта. Во всех шаблонах есть несколько примеров справочных страниц, демонстрирующих оформление основных элементов. Это поможет вам начать работу. При создании проекта можно изменить все элементы дизайна путем редактирования CSS-файл проекта, который автоматически создается на основе дизайна шаблона.
Публикация
По завершении разработки проекта документации вы публикуете его, чтобы создать интерактивное руководство пользователя. Так создается публикация. Каждая публикация проекта отображается как дочерний элемент проекта на странице Проекты. Один проект может иметь несколько публикаций. Публикации будут видны читателям при открытии главной страницы вашего портала документации. Также можно скрыть определенные публикации или сделать их доступными только для авторизованных читателей после входа в систему — это контролируется таким свойством публикации как «Видимость». В процессе публикации система Документерра обработает все динамические элементы и сгенерирует их в окончательном виде: переменные, сниппеты, условные блоки — все они будут представлены в виде простого HTML-контента.
Страница
Подход постраничного создания документации предполагает, что руководство пользователя — это не один длинный документ, а набор небольших логически организованных документов. Эти небольшие документы называются страницами. Каждая страница имеет свое название и содержание. Страницы организованы в виде древовидной навигационной структуры, представленной на панели Дерева страниц — читатели используют эту панель для навигации по страницам.
Понятия, связанные с переводом/локализацией
С добавлением модуля Перевода в системе Документерра появился целый пласт новых понятий. Подробнее о терминологии, связанной с переводом/локализацией, читайте здесь: Создание руководства с несколькими версиями: Термины локализации.
Дерево страниц
Дерево страниц представляет собой логически организованную древовидную структуру страниц. Узлы Дерева страниц могут иметь связанные с ними страницы справки (они отображаются при щелчке на узле) или представлять собой папки без связанной с ними отдельной страницы справки (при щелчке на папке Дерева страниц навигация по страницам не происходит).
Сниппет
Для реализации повторного использования контента можно включить контент одной справочной страницы в другую. Элемент, который вы вставляете в целевую страницу, называется сниппетом. Сниппеты ссылаются на исходную страницу по URL и извлекают весь HTML-контент исходной страницы, чтобы отобразить его в целевой странице. Сниппеты часто используются для реализации повторяющихся частей страниц, таких как верхние или нижние колонтитулы.
Переменная
Переменные — это текстовые строковые значения, имеющие уникальное имя в рамках проекта. Переменные используются для хранения значений, используемых во многих местах руководства пользователя, а также для их централизованного обновления. Хорошим примером является версия программного продукта. Если в документации упоминается номер версии, поместите его в переменную и вставляйте при необходимости. Если необходимо изменить номер версии, то изменяется значение переменной. При этом все страницы, где она упоминается, остаются без изменений.
Условный блок
Часть содержания страницы справки можно сделать условной. Это означает, что данная часть может быть включена или не включена в публикацию в зависимости от конфигурации, выбранной при публикации. Для каждого условного блока можно указать, в какие конфигурации публикаций он должен включаться и из каких исключаться. Наиболее распространенными сценариями применения условных блоков являются: удаление колонтитулов страниц при публикации для последующего экспорта в PDF, замена видеороликов их URL-адресами при выводе на печать и т.д.
Файловое хранилище
При создании онлайн-документации часто возникает необходимость вставить скриншот, шаблоны файлов и т.д. Чтобы использовать эти файлы в документации в системе Документерра, загрузите их в файловое хранилище Документерры. Вы можете вставлять изображения из хранилища в справочные страницы и давать ссылки на скачивание шаблонов файлов, загруженных в хранилище.
Стили
При редактировании контента страницы можно использовать различные стили текста — сделать шрифт жирным/подчеркнутым/курсивным, изменить размер и цвет шрифта и т.д. В дополнение к этим опциям встроенной стилизации Документерра поддерживает расширенную стилизацию онлайн-документации с помощью CSS. В настройках проекта отображается список CSS-файлов проекта. CSS-файлы будут загружаться при просмотре любой страницы справки анного проекта. При создании проекта из шаблона готовый CSS-файл будет включен в этот проект. В CSS-файле находятся все стили, определяющие выбранный вами шаблон, — цвета, фоны, специальные символы-маркёры для оформления списков и т.д. Таким образом, вы можете легко изменить внешний вид проекта онлайн-документации с помощью стилей, заданных в CSS-файле. В проектах и публикациях могут использоваться одни и те же CSS-файлы, а также свои собственные уникальные файлы.
Скрипты
Скриптинг — это передовая концепция, позволяющая реализовать любое динамическое поведение вашей интерактивной документации. В каждый проект может быть включено несколько скрипт-файлов (*.js) — их список можно посмотреть в настройках проекта. Данные скрипт-файлы будут загружаться каждый раз, когда открывается страница справки. Возможно, вам захочется добавить скрипт-файлы в онлайн-справку, чтобы использовать готовый синтаксический выделитель для примеров кода или предоставить читателям возможность каким-либо образом взаимодействовать с контентом.
Условный тег
Условные теги — это именованные конфигурации, используемые для динамических публикаций. Элементы контента (текстовые блоки, элементы Дерева страниц, CSS-файлы) могут быть включены или исключены на основе настроек их условных тегов и тегов, указанных в Мастере публикаций. При публикации проекта Документерра обработает все условные блоки, чтобы либо включить, либо исключить их из контента.
Конфигурация экспорта
Документерра поддерживает экспорт руководств в такие форматы оффлайн-документации, как PDF, DOCX, ePub и т.д. В процессе экспорта пользователь может указать ряд параметров, влияющих на конечную публикацию — нумерацию страниц, стили заголовков и т.д. Чтобы не указывать параметры экспорта каждый раз, в Документерре можно создать конфигурацию экспорта, в которой сохраняются все параметры для дальнейшего использования. Конфигурации экспорта хранятся внутри публикаций, для которых они были созданы. Управлять конфигурациями экспорта можно через настройки публикации.