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

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).

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

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

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

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

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