Создание документации

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

Проект — это контейнер для создаваемых страниц, а страница — это отдельный самостоятельный раздел документа, который должен быть значимым сам по себе. Близкой аналогией проекта может быть отдельный файл Word, а для страницы — одна глава. Однако в файле MS Office Word все главы хранятся в одном документе, в то время как в проекте Документерры каждая страница является отдельным документом.

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

Создавайте и редактируйте контент

Документерра предлагает мощный редактор, который позволяет легко создавать статьи на разных уровнях, благодаря режимам Дизайн и HTML.

Режимы Дизайн и HTML

Режим Дизайн предлагает удобный интерфейс для редактирования контента, аналогичный тому, что вы видите в программных средствах обработки текстов, таких как MS Office Word или Google Sheets. Он позволяет использовать все знакомые функции редактирования и стилизации текста, такие как выделение текста жирным шрифтом или курсивом, изменение шрифтов, создание списков и т.д., а также работать с различными типами контента, такими как изображения / GIF, видео, ссылки, примеры кода, таблицы, вкладки и т.д. Можно даже встроить внешние данные, такие как диаграммы или математические уравнения.   Прочитать всю информацию об упомянутых функциях можно в разделе Редактор страниц. 

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

Вы можете добавить в страницы встроенные элементы навигации, такие как  хлебные крошки, связанные статьи  или  содерждание статьи , о которых вы можете прочитать в следующем разделе:  Добавление элементов навигации.

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

Повторно используйте контент

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

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

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

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

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

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

Концепция сниппетов содержимого схожа с концепцией переменных. Однако подход несколько иной: Сниппеты состоят из отдельных страниц, в то время как переменные представляют собой текстовые строковые значения, хранящиеся в настройках портала или проекта. 

Вы можете использовать Условный контент , которое работает на основе  тегов. С его помощью вы можете включить содержимое в одну публикцию и исключить его из другой, что позволит вам получить разные публикации из одного и того же источника.

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

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

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

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

Прочитайте соответствующий раздел нашего Руководства пользователя, чтобы узнать больше об этой функциональности:  Единый источник и динамическая условная публикация.

Прочие функции

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

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

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