Единая среда для создания документации избавляет от необходимости использовать множество разных инструментов. Встроенный интерфейс Git, интегрированный инструмент сборки, автоматизированные тесты, готовый к использованию и настраиваемый макет позволяют сосредоточиться на главном — вашем контенте.
Теперь вы можете объединить преимущества Markdown с семантической разметкой. Можно придерживаться одного формата или обогатить Markdown семантическими атрибутами и элементами, диаграммами Mermaid и математическими формулами LaTeX.
Writerside помогает обеспечить качество и единообразие документации за счет более чем 100 проверок в редакторе, а также тестов в режиме превью и во время сборки.
В режиме превью документы отображаются именно так, как их увидят ваши читатели. Можно просмотреть одну страницу в IDE или открыть весь сайт документации в браузере, не запуская сборку.
Переиспользуйте все, что угодно: от небольших фрагментов текста до целых разделов вашей документации. Будьте гибкими с помощью фильтров и переменных. Используйте готовые шаблоны для сложных элементов разметки или создавайте свои.
Чтобы создать документацию для пользователей и руководство по использованию API, больше не нужно переключаться между разными инструментами. Интегрируйте API-документацию в свой справочный сайт, публикуйте ее в том же формате и дополняйте автоматически сгенерированные части контентом, написанным вручную.
Этот проект возник из наших собственных потребностей. Мы накопили больше 10 лет опыта написания документации для платформы IntelliJ и опросили сотни потенциальных пользователей. У нас был длинный список функций, которые хотелось бы иметь, и множество проблем, которые необходимо решить. Мы готовы решать их одну за другой.
Хотите нам в этом помочь? Попробуйте 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.
Вы с нами?
Мы обожаем документацию и хотим создать лучший инструмент для тех, кто ее пишет. Будет здорово, если вы нам поможете. Давайте общаться!
Подпишитесь на рассылку
Чтобы получать новости о Writerside и полезные советы по созданию документации, укажите свою почту: