JetBrains запустила Writerside для документирования

Проекты создаются на базе HTML-проектов, которые можно развернуть как статические веб-сайты или опубликовать как GitHub Pages, GitLab или TeamCity Cloud. 

JetBrains выпустила общедоступную предварительную версию Writerside, нового редактора документации, который основан на внутренних инструментах компании. Writerside работает либо как отдельная IDE, либо как плагин для других IDE JetBrains, а проекты создаются для того, чтобы стать веб-сайтами документации.

Документация Writerside пишется или в Markdown, или в семантической разметке (XML). JetBrains подталкивает пользователей к семантическому варианту, особенно для более крупных проектов, поскольку он имеет больше функций и обеспечивает согласованность. Семантическая разметка заимствует многие элементы из HTML, включая такие знакомые теги, как <p>, <a>, <img>, <table> и многие другие. Однако некоторые вещи отличаются: список — это <list>, а не <ul> или <ol>. Нажатие < в редакторе отображает список всех допустимых элементов для конкретного контекста, а нажатие F1 отображает панель справки для выбранного элемента — функция, которая наиболее полезна для изучения разметки.

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

Writerside имеет широкую поддержку интеллектуальных действий, таких как преобразование блока контента в другой формат, также массив шаблонов для часто используемых элементов, таких как вкладки, таблицы и списки. Встроена поддержка общих шаблонов, таких как пошаговые объяснения, в данном случае с помощью тегов <procedure> и <step>. Существует также тег <tldr> (слишком длинный, не читал) для быстрого краткого изложения информации, ограниченный одним на странице. Добавление фрагментов кода легко осуществляется с помощью тега <code-block>. Существует также тег, который генерирует ссылку на API из файла спецификации OpenAPI (Swagger).

Image 13
Помощь по тегам в Writerside 

Проекты создаются на базе HTML-проектов, которые можно развернуть как статические веб-сайты или опубликовать как GitHub Pages, GitLab или TeamCity Cloud. Поиск можно осуществлять через Algolia , хотя для масштабного использования потребуется платная учетная запись.

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

Тем не менее, что касается документации программного обеспечения, проекты Writerside уязвимы из-за несоответствия коду, в отличие от таких подходов, как Javadoc, JSDoc или Doxygen, где документация генерируется из комментариев в самом коде, что разработчикам легче поддерживать в курсе.

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

«С Writerside вы получаете современную веб-справку с фиксированным макетом, адаптированную для мобильных устройств», — сообщили в релизе.

 

Читайте также
Что нового в стабильных версиях браузеров Firefox и Chrome в марте
Что нового в стабильных версиях браузеров Firefox и Chrome в марте
Что нового в стабильных версиях браузеров Firefox и Chrome в марте

Рассмотрим новые функции, которые добавили в веб-платформы Firefox 123 and Chrome 122.

Deno 1.40: будущий Temporal API и декораторы JavaScript
Deno 1.40: будущий Temporal API и декораторы JavaScript
Deno 1.40: будущий Temporal API и декораторы JavaScript

В Deno 1.40 реализовали предстоящий Temporal API JavaScript для расширенных операций с датой и временем, а также новейшее предложение декораторов JavaScript для мета- и аспектно-ориентированного программирования.

Что значат стабильные версии браузеров Firefox 122, Chrome 121 и Safari 17.3 в феврале 2024
Что значат стабильные версии браузеров Firefox 122, Chrome 121 и Safari 17.3 в феврале 2024
Что значат стабильные версии браузеров Firefox 122, Chrome 121 и Safari 17.3 в феврале 2024

Рассказываем о некоторых интересных функциях, которые появились в стабильных и бета-версиях веб-браузеров в январе 2024 года.

Angular V17: главные обновления
Angular V17: главные обновления
Angular V17: главные обновления

Вышло обновление фреймворка Angular V17: увеличение производительности, расширенные возможности, разработка с прицелом на будущее.