Мы постоянно улучшаем Документерру на основе обратной связи наших клиентов. Ноябрьскому релизу будут особенно рады сторонники подхода 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 сценария:
- Обновление одной или нескольких страниц API-документации. Допустим, у вас есть руководство пользователя, которое содержит не только обычный контент, но и страницы API-документации, сгенерированной на сторонней платформе. Теперь ваши разработчики могут создать утилиту, при помощи которой обновлённая API-документация будет автоматически загружаться в Документерру. То есть вам не придётся переносить обновлённые страницы вручную.
- Частичное обновление страниц API-документации. Представьте, что у вас есть обычные страницы документации — их создали технические писатели на вашем портале. Кроме того, часть контента на этих страницах — это автоматически сгенерированная документация из сторонней утилиты. В этом случае API тоже позволит вам обновлять страницы за несколько секунд, а не делать это вручную.
Экспорт чистого HTML
Некоторым техническим писателям нужен экспорт чистого HTML, чтобы каждая страница проекта сохранялась в виде файла без навигации. Теперь в Документерре можно это сделать. Такой вариант актуален для следующей ситуации: вы разрабатываете на Документерре контент, часть которого нужно продублировать на других платформах (например, на Zendesk или Salesforce), но экспорт в HTML5 WebHelp не подходит из-за функций навигации и поиска. Новый формат экспорта решает такие задачи лучше!
Импорт из Swagger/OpenAPI
Обычно технические писатели инструкции создают в одной программе, а API-документацию — в другой. Из-за этого нужный контент сложнее найти, так как вся информация находится на разных порталах. Ноябрьский релиз решил эту проблему: теперь можно импортировать файлы Swagger/OpenAPI в проект Документерры и управлять разной документацией на одной платформе.
Импорт и экспорт в формат Документерры
Если нашим пользователям нужно было создать резервную копию данных, ранее они могли скачать проекты в форматах CHM и HTML. Такой сценарий хорошо работал с простым контентом, однако динамические элементы (условный контент, переменные, сниппеты) при этом становились статическими.
Теперь авторы могут скачать проекты в формате Документерры, который сохраняет разметку текста с динамическими элементами и проектными метаданными. Эта функция пригодится в следующих случаях:
- Резервное копирование проекта. Если у вас есть ненужные проекты, которые жалко удалить, просто скачайте их в формате Документерры. Поскольку наш формат основан на XML, то экспортированные проекты будет легко прочитать. Вы можете открыть резервную копию в любом текстовом редакторе или импортировать её обратно в Документерру.
- Объединение нескольких проектов. Иногда автору нужно соединить два проекта, но тратить время на копирование каждой страницы не хочется. В этом случае вы можете скачать один проект в формате Документерры и импортировать его в другой проект.
- Хранение данных в Git. Этот сценарий подойдёт для тех пользователей, которые хотят хранить документацию в одной ветке с кодом и просматривать историю изменений.
- Миграция контента на другой портал. Например, у вас есть несколько порталов: основной и дополнительные. Вспомогательные порталы нужны для других локальных рынков или отдельных линеек технологических продуктов. В этом случае самый удобный способ перенести проекты с основного портала на дополнительные — использовать формат Документерры.
Улучшенные таблицы
С таблицами стало работать еще удобнее благодаря следующим функциям:
- Горизонтальная прокрутка широких таблиц. Иногда в таблицах получается так много данных, что приходится сильно сужать столбцы. Из-за такого решения таблицы читать сложнее. Благодаря ноябрьскому обновлению авторы могут забыть об этой проблеме: система автоматически добавит горизонтальную прокрутку, если таблица будет слишком широкой для читательского интерфейса.
- Автоматическое изменение контента в ячейках. Система уменьшит картинки в ячейке, если вы поменяете размер столбца. Это же относится и к длинным словам — они автоматически перенесутся на новую строку, то есть вам не придётся вручную редактировать содержимое ячеек, если вы измените ширину столбцов.
- Сортировка данных. Теперь автор может создавать сортируемые таблицы — это поможет вашим читателям изменять порядок данных и быстрее находить нужную информацию.
Предварительный просмотр в режиме читателя
Автору важно знать, как страница проекта будет выглядеть для читателей. Благодаря ноябрьскому обновлению можно нажать на кнопку в редакторе, и Документерра покажет вам предпросмотр страницы.
Чтобы попасть в превью, откройте редактор и нажмите на кнопку «Перейти в режим читателя». Для возвращения в проект выберите «В режим автора».
Заключение
В ноябрьском релизе мы уделили особое внимание тому, чтобы вы могли работать с разной документацией на одной платформе. Благодаря новым методам API способов интеграции Документерры с другими системами стало больше.
Еще наши пользователи теперь могут экспортировать документацию в формат Документерры, импортировать файлы из Swagger/OpenAPI, эффективнее работать с таблицами, а также открывать предпросмотр страницы в режиме читателя. Эти и другие обновления позволят вам управлять технической документацией еще удобнее!
