Пишите, тестируйте, собирайте и публикуйте тьюториалыинструкцииAPI-документациюруководстваSDK-документацию

Самая эффективная среда разработки теперь адаптирована для написания документации

Все, что нужно для Docs-as-code, у вас под рукой

Пайплайн Docs-as-code

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

Сочетание Markdown и XML

Теперь вы можете объединить преимущества Markdown с семантической разметкой. Можно придерживаться одного формата или обогатить Markdown семантическими атрибутами и элементами, диаграммами Mermaid и математическими формулами LaTeX.

Автоматизированный контроль качества

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

Режим превью

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

Один источник

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

API и документация по продукту, собирайтесь!

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

Как это работает

Writerside разработан писателями
для писателей

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

Хотите нам в этом помочь? Попробуйте Writerside и поделитесь с нами своими впечатлениями!

С помощью Writerside вы сможете создавать документацию, как у этих продуктов

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

Вопросы и ответы

Сейчас, в рамках программы раннего доступа, Writerside доступен полностью бесплатно.

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

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

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

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

Файлы можно хранить локально, но мы рекомендуем использовать Git-репозиторий. В Writerside есть удобный интерфейс для всех операций с Git, управления ветками и разрешения конфликтов. Вы также можете использовать другую поддерживаемую систему контроля версий, например Subversion или Perforce.

Мы сторонники онлайн-документации, но понимаем, что иногда документация может потребоваться в печатном виде. С января 2024 года мы поддерживаем вывод документации в PDF.

Writerside позволяет собрать проект локально и создает ZIP-файл, который вы можете загрузить на свой сайт или разместить на GitHub Pages, Amazon AWS, Netlify или любом другом хостинге. Мы рассматриваем возможность предоставления собственного хостинга документации.

Если вы пользуетесь CI/CD-сервером, мы можем предоставить скрипты сборки в виде Docker-контейнера, который вы сможете использовать для конфигурации сборки документации.

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

Между тем мы работаем над собственным поисковым решением.

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

  • Менять внешний вид верхнего и нижнего колонтитулов.
  • Добавлять логотипы и копирайт.
  • Выбрать один из трех цветовых пресетов (мягкий, контрастный или яркий) с поддержкой светлой и темной темы.
  • Выбирать цвет выделенных элементов.
  • Встраивать ссылки на социальные сети и другие ресурсы.

Мы планируем добавить больше опций и сделать настройку документов еще более гибкой.

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

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

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