Запросить демо

Вебинар о Лучших практиках единого источника · 25 июня 2024, 18:00 (МСК)

Зарегистрироваться
Запросить демо

Ноябрьский релиз Документерры: что нового

30.11.2022

Мы постоянно улучшаем Документерру на основе обратной связи наших клиентов. Ноябрьскому релизу будут особенно рады сторонники подхода docs-as-code и технические писатели, которые специализируются на API-документации. 

Интерфейс на русском

Мы добавили русский язык интерфейса, чтобы вам было удобнее работать с Документеррой. Также у нас появилось руководство пользователя на русском — так вы разберётесь с платформой быстрее. 

Новые функции API 

У Документерры давно есть API, и наши клиенты активно его используют. Поэтому мы решили облегчить пользователям работу и сделали так, чтобы способов интеграции Документерры с другими программами стало больше. Благодаря ноябрьскому обновлению через API доступны новые операции:  

  • Страницы: создание, изменение, обновление и удаление. 
  • Проекты: создание резервной копии. 
  • Элементы дерева страниц (папки в том числе): создание, изменение и удаление. 
  • Хранилище файлов Документерры: скачивание, создание, обновление, изменение и удаление файлов и папок. 

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

API сценарий №1: продублируйте внешнюю базу знаний в Документерре

Допустим, ваша служба технической поддержки пишет статьи для базы знаний в Salesforce или Zendesk. Но вы хотите, чтобы этот контент был на одном портале с документацией, ведь так клиентам легче искать информацию. Благодаря новым методам API ваши разработчики могут создать утилиту, которая добавит статьи из сторонней системы на портал Документерры и будет автоматически обновлять этот контент.

API cценарий №2: настройте импорт индивидуального формата 

Некоторым пользователям нужно импортировать в Документерру контент из формата, который у нас не поддерживается. Теперь при помощи API ваши разработчики могут создать утилиту для импорта, которая будет читать ваш индивидуальный формат и адаптировать контент для Документерры. 

API cценарий №3: обновляйте файлы автоматически

Допустим, у вас есть файлы, которые нужно сделать частью онлайн-документации. Например, это могут быть конфигурационные файлы. Если вы используете системы автоматизации сборки (Jenkins, Maven, Bamboo, TeamCity и другие), то теперь вы можете автоматически загружать файлы в хранилище Документерры. С новыми методами API вам не нужно обновлять файлы вручную. 

API cценарий №4: создайте внешние средства просмотра

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

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

API cценарий №5: продублируйте автоматически сгенерированную API-документацию

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

Вы можете импортировать в Документерру файлы OpenAPI — об этой новой функции мы расскажем далее. Но если даже вы не работаете со спецификацией OpenAPI, вы можете настроить индивидуальную синхронизацию при помощи новых API-функций. 

Для обновления автоматически сгенерированной API-документации есть 2 сценария: 

  1. Обновление одной или нескольких страниц API-документации. Допустим, у вас есть руководство пользователя, которое содержит не только обычный контент, но и страницы API-документации, сгенерированной на сторонней платформе. Теперь ваши разработчики могут создать утилиту, при помощи которой обновлённая API-документация будет автоматически загружаться в Документерру. То есть вам не придётся переносить обновлённые страницы вручную. 
  2. Частичное обновление страниц API-документации. Представьте, что у вас есть обычные страницы документации — их создали технические писатели на вашем портале. Кроме того, часть контента на этих страницах — это автоматически сгенерированная документация из сторонней утилиты. В этом случае API тоже позволит вам обновлять страницы за несколько секунд, а не делать это вручную. 

Экспорт чистого HTML

Некоторым техническим писателям нужен экспорт чистого HTML, чтобы каждая страница проекта сохранялась в виде файла без навигации. Теперь в Документерре можно это сделать. Такой вариант актуален для следующей ситуации: вы разрабатываете на Документерре контент, часть которого нужно продублировать на других платформах (например, на Zendesk или Salesforce), но экспорт в HTML5 WebHelp не подходит из-за функций навигации и поиска. Новый формат экспорта решает такие задачи лучше!

Импорт из Swagger/OpenAPI

Обычно технические писатели инструкции создают в одной программе, а API-документацию — в другой. Из-за этого нужный контент сложнее найти, так как вся информация находится на разных порталах. Ноябрьский релиз решил эту проблему: теперь можно импортировать файлы Swagger/OpenAPI в проект Документерры и управлять разной документацией на одной платформе.

Импорт и экспорт в формат Документерры

Если нашим пользователям нужно было создать резервную копию данных, ранее они могли скачать проекты в форматах CHM и HTML. Такой сценарий хорошо работал с простым контентом, однако динамические элементы (условный контент, переменные, сниппеты) при этом становились статическими. 

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

  • Резервное копирование проекта. Если у вас есть ненужные проекты, которые жалко удалить, просто скачайте их в формате Документерры. Поскольку наш формат основан на XML, то экспортированные проекты будет легко прочитать. Вы можете открыть резервную копию в любом текстовом редакторе или импортировать её обратно в Документерру. 
  • Объединение нескольких проектов. Иногда автору нужно соединить два проекта, но тратить время на копирование каждой страницы не хочется. В этом случае вы можете скачать один проект в формате Документерры и импортировать его в другой проект. 
  • Хранение данных в Git. Этот сценарий подойдёт для тех пользователей, которые хотят хранить документацию в одной ветке с кодом и просматривать историю изменений. 
  • Миграция контента на другой портал. Например, у вас есть несколько порталов: основной и дополнительные. Вспомогательные порталы нужны для других локальных рынков или отдельных линеек технологических продуктов. В этом случае самый удобный способ перенести проекты с основного портала на дополнительные — использовать формат Документерры.

Улучшенные таблицы

С таблицами стало работать еще удобнее благодаря следующим функциям: 

  1. Горизонтальная прокрутка широких таблиц. Иногда в таблицах получается так много данных, что приходится сильно сужать столбцы. Из-за такого решения таблицы читать сложнее. Благодаря ноябрьскому обновлению авторы могут забыть об этой проблеме: система автоматически добавит горизонтальную прокрутку, если таблица будет слишком широкой для читательского интерфейса. 
  1. Автоматическое изменение контента в ячейках. Система уменьшит картинки в ячейке, если вы поменяете размер столбца. Это же относится и к длинным словам — они автоматически перенесутся на новую строку, то есть вам не придётся вручную редактировать содержимое ячеек, если вы измените ширину столбцов.
  1. Сортировка данных. Теперь автор может создавать сортируемые таблицы — это поможет вашим читателям изменять порядок данных и быстрее находить нужную информацию.

Предварительный просмотр в режиме читателя

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

Чтобы попасть в превью, откройте редактор и нажмите на кнопку «Перейти в режим читателя». Для возвращения в проект выберите «В режим автора». 

Заключение

В ноябрьском релизе мы уделили особое внимание тому, чтобы вы могли работать с разной документацией на одной платформе. Благодаря новым методам API способов интеграции Документерры с другими системами стало больше. 

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