Инструмент используется в JetBrains уже более 10 лет, и, по словам команды, продукты JetBrains, от языка программирования Kotlin до IntelliJ Platform SDK, используют Writerside для создания своей документации.
Компания JetBrains выпустила инструмент под названием Writerside в режиме раннего доступа. Этот инструмент разработан для помощи разработчикам и техническим писателям в создании технической документации. Writerside основан на внутреннем инструменте компании JetBrains, который они использовали для создания документации к своим программным продуктам.
По словам представителей JetBrains, Writerside позволяет разработчикам и техническим писателям совместно работать над документацией для продуктов. Это включает в себя описание API, создание учебных материалов, руководств для разработчиков и инструкций, прямо в их любимой среде разработки JetBrains (IDE) или с использованием отдельного инструмента, созданного на той же платформе.
Этот инструмент уже более 10 лет используется в компании JetBrains, и, согласно команде, продукты компании, включая язык программирования Kotlin и платформу IntelliJ SDK, используют Writerside для создания своей документации.
Анна Гаспарян, руководитель направления Writerside в компании JetBrains, отмечает: "Если технические писатели используют те же инструменты, что и разработчики, такие как Git, автоматическая проверка и сборочные процессы, это способствует не только качеству конечного продукта, но и упрощает всей команде процесс работы над документацией, рецензированием и отслеживанием изменений".
Writerside поддерживает как Markdown, так и собственную семантическую разметку на основе XML, и позволяет пользователям вводить семантические атрибуты и элементы, а также "на лету" преобразовывать фрагменты Markdown, предоставленные другими участниками, в XML.
Инструмент автоматически проверяет наличие неработающих ссылок, отсутствие ресурсов, неверные значения атрибутов и дублирующиеся идентификаторы. Кроме того, он обеспечивает мгновенную проверку кода с встроенными инспекциями. Writerside также позволяет автоматизировать проверку соблюдения собственных орфографических и стилистических правил.
После создания документа пользователи могут просматривать его в режиме реального времени с подсветкой ошибок. Это, по мнению JetBrains, решает проблемы, связанные с ограниченным доступом к процессам непрерывной интеграции и непрерывной доставки (CI/CD) или долгими сборками для небольших обновлений.
Writerside также включает инструмент проверки орфографии и исправления грамматических ошибок, основанный на искусственном интеллекте, который разработала компания JetBrains и который поддерживает более 25 языков, включая английский, немецкий, испанский и китайский.
Writerside доступен как плагин для сред разработки IDE JetBrains, а также как отдельное приложение.
Комментарии (30)
segment
18.10.2023 09:20А получившуюся документацию можно встраивать на сайт?
suprunchuk Автор
18.10.2023 09:20+3
На данный момент я нашел кнопку запуска, и у меня на локальном сервере запустился сайт
Vanger
18.10.2023 09:20А в PDF оно научилось рендерить?
ritorichesky_echpochmak
18.10.2023 09:20Правильно оформленный Markdown можно выгнать в PDF, EPUB, HTML, doc(x) и сайтики целым вагоном тулов. Но, например, тот же Obsidian нужно немного переконфигурить сначала (чтобы корявые wikilinks заменялись на формат принятый в Markdown и пути к изображениям не вели в сказочные места)
Vanger
18.10.2023 09:20Ну это да, правильно оформленный без вопросов, но хочется видеть тулзу для авторов в законченном виде, а не только рендеринг в HTML.
Я уже не говорю про применение шаблонов к PDF или ODT, Хочется создать документ и не городить кучу пайплайнов или настраивать окружение сборки на машине что бы получить PDF, для этого есть VSCode ;-)ritorichesky_echpochmak
18.10.2023 09:20Хороший вопрос... Здесь непонятно. Тот же Obsidian имеет кучу плагинов для "просто выгнать в PDF", но когда появляются вопросы с изменением стилей/шаблонов и новые хотелки типа табличек, превью не только для фото, но и любого медиаконтента (вплоть до отдельных параграфов из других документов) - тут уже придётся тулы и пайплайны крутить полюбому)
Vanger
18.10.2023 09:20+2Так Obsidian не претендует на тулзу для Техписов, как это делают JetBrains. Это софт для ведения заметок. Да многие его используют для ведения документации. А тут утилита для создания документации, как отдельный продукт, и уже он не имеет части базового функционала. Если не ошибаюсь тот же Obsidian бесплатен и экспорт в PDF там есть.
atshaman
18.10.2023 09:20+2Насколько я знаю - нет. А кувыркаться через pandoc - прям такоЭ себе развлечение - какой-нибудь mermaid, svg рисунки внутри - и оно разным образом не работает под linux\windows ).
olku
18.10.2023 09:20+4JetBrains, вот такое надо в architecture-as-service бизнесе сейчас
https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/Все компоненты есть, все опенсорс, нужен редактор где их "смешать но не взбалтывать".
13werwolf13
18.10.2023 09:20-2интересно, когда наступет тот день что до Jetбрейнсов дойдёт глупость выпускания одной и той же IDE с разным набором базовых плагинов под видом разных IDE?
izogfif
18.10.2023 09:20+4Поясните, в чем состоит глупость, тогда и до них, и до меня дойдет.
ritorichesky_echpochmak
18.10.2023 09:20Возможно ему хочется видеть это в составе IDE, а не отдельным продуктом. Тот же DataGrip обеспечивает работу с БД есть как самостоятельный продукт (очень удобно в саппорте: создал директорию с датой и номером таски, внутри все файлы к ней - Markdown с описанием, заметки по найденным нюансам, ссылки на документацию, SQL-файлы с запросами, http-файлы с запросами, логи и т.д.), так и в рамках всех основных IDE (по крайней мере в платных версиях: PyCharm PRO, Rider..., очень удобно пилить фичи). Когда всё в одном месте и не нужно запускать несколько тяжёлых IDE которые потом ещё полчаса будут что-то индексировать (не давая в это время даже поиск по файлам сделать нормально), а потом ещё полчаса будут пытаться что-то протолкнуть в копилоты (которые не работают, потому что прокси отключены, потому что глобальные прокси ломают локалхост, а плагин персонально в прокси не умеет)...
andToxa
18.10.2023 09:20+1а что мешает, если есть такое желание, подключать это плагинами в одну IDE?
кому нравится так - поставит все плагинами, кому эдак - будет отдельные IDE под разные задачи использовать.ritorichesky_echpochmak
18.10.2023 09:20+2Я лишь предположил, в чём суть первого вопроса. Пока непонятно, как фичи этой "новой IDE" отличаются от того, что уже есть штатно в любом продукте JB.
И нет хороших примеров документации оформленной этим инструментом так, чтобы и работать было приятно и при коммите в гитхабчеги оно не рассыпалось потому что где-то кому-то что-то зачесалось сделать ну очень по-своему (как у Obsidian из коробки со ссылками и путями к изображениям - нужно конфигурить под себя)
atshaman
18.10.2023 09:20+3Так оно вполне себе подключается - я из PyCharmPro работаю - почему нет? Но если бы я работал только с документацией - это был бы очевидный overkill.
7Euro
18.10.2023 09:20+2Так-то уже дошло. Они выкатили в бету (вроде) универсальную ide, но, как мне кажется, остальные все равно будут поддерживать, все таки нид мани
ritorichesky_echpochmak
18.10.2023 09:20+1Кстати, про "универсальную" IDE, если речь про JetBrains Space, то интересно, будет ли доступна эта история с какого-нибудь планшетотелефона, потому что сейчас хоть JetBrains Space и доступен в Google Play, непосредственно фичи IDE из него выпилены
nalinor
18.10.2023 09:20+1Скорее всего, речь идёт про JetBrains Fleet, который на данный момент в Preview, поэтому ещё и бесплатный
ritorichesky_echpochmak
18.10.2023 09:20+6В DataGrip можно писать Markdown в котором вставляешь примеры запросов и их можно прям из документации выполнять. Не хватает только In-Editor Results (чтобы не ходить каждый раз в Services) чтобы получить прям нормальный аналог Jupyter Notebook
В некоторых вариантах HTTP Client к VSCode можно http/rest запросы выполнять прямо из Markdown аналогично. Хочется чтобы плагин HTTP Client к JetBrains тоже умел выполнять примеры запросов прямо из документации и нормально всё подсвечивал прям в той IDE, в которой ведёшь проект. Хочется чтобы починили
Accept-Encoding: br(баге уже больше года) и чтобы плагин научился в loop statements , а то сейчас грустно этим пользоваться, приходится прыгать в VSCode.Пока всего этого нет, Obsidian и VSCode смотрятся предпочтительнее в плане написания документации. Ну и раскатывается это всё по коммиту настроенными пайплайнами через Hugo в красивый сайтец с доками. Hugo быстр и к нему есть куча оптимизированных для всего и вся шаблонов (100 попугаев из 100 к читабельности, accessibility, SEO и т.д.)
vic_1
18.10.2023 09:20-6JetBrains ушёл из РФ, так что им пофигу ваши хотели, а нам их поделки, потому что легально никак это не попользовать
ris58h
18.10.2023 09:20+4потому что легально никак это не попользовать
Бесплатные версии ничто не мешает использовать.
poslannikD
18.10.2023 09:20Отсутсвие фич платных версий, мешает использовать бесплатные. Тот же профилировщик в IDEA.
ritorichesky_echpochmak
18.10.2023 09:20+3Все же знают, что без профилировщика у разраба ни одного дня не проходит... Как раз сегодня я... опять не запускал профилировщик. А последний раз я по нём скучал... не помню даже в этом ли году.
С другой стороны я плачу из запрещённой страны за лицензии и всё равно не вижу проблемы. Кто хочет пользоваться - пользуется. Кто не хочет - оправдывает любую дичь, в т.ч. лозунги "не нужны нам их поделки", продолжая пользоваться в 99% случаев иностранным софтом (т.е. даже не выходцев отсюда, а полностью иностранным) или оным же с перекроенным логотипом. С железом примерно всё то же самое. Есть ещё стойкое ощущение, что такие комментарии про "их поделки" оставляют люди вообще не видевшие IDE в глаза и не имеющие сколь-нибудь представления о вайтишечке
olku
PlantUML есть? Сейчас плагин к IDE не умеет рендерить превью маркдаун со вставками. Arc42 есть? Это уже стандарт документации.