AsciiDoc или DITA: какой язык разметки выбрать?

Я работаю техническим писателем два года, за это время мне довелось познакомиться с тяжёлой DITA и лёгким AsiiDoc. Если вы решили перейти к Docs as Code, я сравню два инструмента и, надеюсь, помогу вам сделать правильный выбор.

Для начала небольшой экскурс в языки разметки и для чего они нужны. Языки разметки (markup languages) используются для написания различной документации, например, руководств по использованию чего-либо. Это удобнее, чем просто писать документацию в текстовом редакторе типа Ворда, потому что языки разметки отделяют текст от форматирования. Автор пишет документацию на языке разметки в исключительно текстовом виде, а на выходе запускает сборку и всегда получает готовый результат в едином форматировании. Также языки разметки позволяют получить несколько результирующих форматов из одного исходного.

С первого дня работы я писал документацию на DITA. Но уже через год возникла потребность всё переделать: перевести в онлайн, сделать версионирование, добавить поиск.

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

Первый параметр - наличие документации

Чтобы начать чем-то пользоваться, всегда лучше сначала прочитать мануал. А при выборе инструмента для технического писателя лучше изучить все доступные мануалы и добавит их в закаладки.

DITA

Для DITA есть один большой и чёткий мануал - это стандарт, описывающий язык разметки совсем полностью. Но читать этот стандарт очень скучно, очень тяжело. Кем нужно быть, чтобы это осилить, я не знаю.

К счастью, существует более читаемая версия - документация от Radu Coravu - создателя Oxygen. Об Oxygen я ещё скажу несколько слов, но позже.

Есть ещё более человекочитаемая версия - учебный курс с примерами - Learning Dita. Когда я хотел лучше понять, как работает DITA, мне этот проект очень пригодился. Особенно помогают примеры и задания на самостоятельное выполнение.

AsciiDoc

AsciiDoc выигрывает по критерию документации, потому что официальная версия документации одна и располагается на официальном сайте docs.asciidoctor с удобным поиском и рубрикацией.

Конечно, есть и другие сайты документации, поиск не всегда выдаёт именно этот первым. Документация на этих сайтах примерно такая же, но бывает устаревшая и неофициальная.

Я не могу присудить победу по этому критерию ни одной из сторон, поэтому пусть будет ничья.

DITA:AsciiDoc 1:1

Работа с исходным кодом

DITA

Технически, исходный код DITA можно было бы редактировать в блокноте. Но такой навык - это особая суперспособность, доступная только богам XML. Короче, это жесть как сложно и непрактично.

AsciiDoc

AsciiDoc тоже можно редактировать и писать в блокноте. AsciiDoc - это всё же скорее текст, приправленный тегами и разметкой, нежели код, содержащий текст. AsciiDoc удобнее читать и быстро редактировать в блокноте, отдаю балл в его пользу.

DITA:AsciiDoc 1:2

Редакторы для работы с исходниками

Писать в блокноте - это хорошо, но удобнее всё же иметь какой-то официальный редактор для работы с кодом.

DITA

Основная утилита для работы с DITA - Oxygen. Главная проблема Oxygen в том, что он платный. Можно купить лицензию на версию и пользоваться ей пожизненно, но ценник у него откровенно грабительский.

Кроме "Кислорода" есть и другие, менее популярные редакторы. Главная проблема этих редакторов в том, что они неудобные на мой субъективный взгляд.

AsciiDoc

Для AsciiDoc нет единственного каноничного редактора. Вместо этого синтаксис и функции AsciiDoc поддерживаются в сторонних IDE через установку сторонних плагинов:

• IntelliJ Idea - бесплатный редактор от JetBrains поддерживает все функции языка разметки и постоянно обновляется. Для работы с AsciiDoc требуется специальный плагин. На сегодняшний день - лучший выбор.

• Visual Studio Code - с плагином AsciiDoc. Плагин только начинает своё развитие, но уже поддерживает синтаксис и основные функции.

• Atom - выглядит неплохо, имеет много плагинов, но я им не пользовался.

• AsciidocFX - слабенький редактор, поддерживающий только синтаксис.

Любой из перечисленных редакторов не стоит ничего, поэтому AsciiDoc снова выигрывает.

DITA:AsciiDoc 1:3

Набор функций

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

Повторное использование

DITA

DITA часто хвалят за крутые возможности повторного использования фрагментов кода. DITA позволяет заимствовать топики целиком или небольшие фрагменты. Но заимствования ограничиваются чёткой структурой. Если в данном топике нельзя использовать какой-то элемент, он не будет заимствован, выдаст ошибку и не выведется в результирующем тексте. При редактировании через Oxygen заимствовать запрещённые элементы не получится, сложно наступить не туда.

Позаимствовать фрагмент - это всегда либо conref для точечного заимствования, либо conref ... conrefend для заимствования от и до.

AsciiDoc

По общему принципу заимствования в AsciiDoc построены аналогично DITA. Включить страницу целиком можно при помощи include::topic.adoc[]. Чтобы включить какой-то фрагмент текста от и до нужно предварительно добавить тег в начало и закрыть его в конце. Приятно, что можно использовать один тег несколько раз в одном топике.

//tag::magic-tag[]
Много-много текста
//end::magic-tag[]
Чуть-чуть текста
//tag::magic-tag[]
Другой текст на той же странице
//end::magic-tag[]

Зато заимствование по тегу делается одной короткой строчкой: include::topic.adoc[tags=magic-tag].

Снова я не могу отдать предпочтение ни одному из инструментов, поэтому отдаю по одному баллу обоим.

DITA:AsciiDoc 2:4

Ключи

Ключи - это самый простой инструмент повторного использования. Например, если у вас есть часто используемый термин, вы можете сделать его ключом и не вводить каждый раз. Если термин изменился, его нужно отредактировать только один раз, в тексте он изменится сам.

DITA

Ключи обозначаются один раз на карту (главный топик) или на каждую страницу. Создайте ключ, задайте ему значение, теперь вы можете применять его по мере надобности. Использовать ключи вне Oxygen сложно, но, наверное, возможно. Другое дело, что лично мне даже в Oxygen работать с ключами очень сложно. Кажется, что проще писать каждый раз термин заново, чем заморачиваться с настройкой ключей.

Зато DITA предлагает инструменты, позволяющие задать для любого ключа целевую аудиторию, область действия и прочее. Грубо говоря, в руководстве "для ixbt" ключ будет отображаться как "Grolribasi", а в руководстве "для своих" будет отображаться как "Авксентий Цезаревич".

AsciiDoc

В AsciDoc ключи называются "атрибуты", но принцип работы тот же - задаёте один раз на странице или в главном топике, используете при случае. Задать атрибут очень легко: :user: Grolribasi. Вызвать атрибут ещё легче: ввести {user}, который в тексте будет заменён на "Grolribasi".

Назначить для атрибута аудиторию или область действия в AsciiDoc без дополнений можно, но немного сложно. Проще и удобнее использовать атрибуты вместе с генератором статических сайтов Antora. Без Antora задать область получится только для отдельного или главного топика. Ну, либо использовать условные конструкции (следующий пункт).

Мне неудобно использовать ключи в DITA, но это мои личные проблемы и не отменяет того, что инструмент сильный, снова один балл каждому конкурсанту.

DITA:AsciiDoc 3:5

Условные конструкции

DITA

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

Если совсем никогда не слышали, то вот пример: создаём небольшое руководство, скажем, на 15 страниц в исходном формате. Запускаем команду для сборки, которая в результате даст нам 3 документа по 5 страниц каждый. Программа сборки сама найдёт инструкцию и разберётся, какие 5 страниц нужно вставить в какой конечный документ. Также при сборке к каждому документу автоматически будут добавлены титульный лист, заключение и т.д.

DITA использует для профилирования специальные файлы в формате .ditaval. Не сказать, чтобы это было супер-просто: нужно назначить профили на нужные страницы, создать .ditaval, хранить его где-то и не забывать его указывать при сборке.

AsciiDoc

Для AsciiDoc предусмотрен похожий механизм, он проще, но тоже требует некоторой ручной работы.

1. Добавляем атрибуты на все страницы руководства, над заголовком.
2. Три руководства - три атрибута.
3. Добавляем условные конструкции к нужному тексту:

• ifdef - текст отображается, если атрибут задан.
• ifndef - текст не отображается, если атрибут задан.
• ifeval - текст отображается, если атрибут соответствует указанному условию. Условия могут быть разные, от простых логических: от простых вроде равно, не равно, больше, меньше до сложных, продиктованных вашей фантазией.

В какой-то степени условия в AsciiDoc настроить легче, чем в DITA, но чтобы научиться их грамотно применять, потребуется навык. При работе с генератором сайтов Antora профилирование немногим легче, а в чём-то даже сложнее. Зато область действия атрибута настроить значительно проще.

Можно задать атрибут для одной страницы, для компонента или для всего сайта. Приправить нужные места условиями idef, ifndef, ifeval и получить на выходе разные руководства. Ну, типа того.

Не отдам балл AsciiDoc, потому что он откровенно слабее в этом плане.

DITA:AsciiDoc 4:5

Выходные форматы и единый источник

Единый источник - основная причина перехода с "формата Ворд" на языки разметки.

Не все разбираются в терминах, на всякий случай раскрою подробнее. Единый источник - это когда, как я говорил выше, из условных 15 страниц исходного кода в результате получается несколько руководств в разных форматах. Например, из AsciiDoc или DITA получить результирующие .pdf, .html, .doc(x). Вносить правки в документы не потребуется, такая вот гарантия внешнего вида результирующих документов.

DITA

DITA позволяет создать сколь угодно результирующих форматов, но с одной оговоркой.

Преобразовать XML во что-либо очень непросто. Для этого потребуется создать преобразования, которые будут задавать правила для экспорта: как будет выглядеть каждый фрагмент и куда он пойдёт. Даже для обычного использования критически необходимо наличие JDK и DITA OT (DITA Open Toolkit).

В принципе, можно использовать встроенные трансформации Oxygen, не устанавливать никакого дополнительного софта, но он всё же платный и очень дорогой.

А если поставить JDK и DITA OT, то можно наслаждаться всеми возможностями DITA и единого источника.

По умолчанию DITA OT предоставляет следующие форматы:

DITA OT позволяет установить любые дополнительные плагины и получить ещё больше форматов. Плагины могут быть уже готовые или собственноручно созданные.

Собственные плагины нужны для того, чтобы результирующий документ выглядел в соответствии со стилем компании. (Проклятые капиталисты, при коммунизме-то всё было одинаковое и никто не выпендривается!). Но для этого вам придётся конкретно начать разбираться в том, как работают XSL-трансформации (или преобразования)!

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

Когда я начал работать с DITA, я не знал ничего об XSL-трансформациях. Через год работы я так и не научился работать с ними, посмотрел только исходный код трансформаций, но испугался и решил не трогать.

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

AsciiDoc

Ситуация с форматами экспорта почти такая же. Использовать экспорт из AsciiDoc немного проще, устанавливать софта нужно чуть меньше и установку можно выполнить из терминала.

По умолчанию в AsciiDoc встроены следующие форматы:

Кроме того можно установить дополнительные официальные аддоны:

Кроме того, как и с DITA, сообщество создало множество неофициальных конвертеров. Через конвертер можно получить почти любой результирующий формат. Самый распространённый конвертер pandoc, который приносит множество дополнительных форматов. Стили для каждого конвертера настраиваются по-своему, что может вводить в заблуждение, но может и облегчить задачу, если ввести примерно такой запрос в поисковике: "asciidoc to нужный формат". Результаты могут обрадовать, но не факт, что они будут.

Но самая приятная возможность Asciidoc - создание сайтов документации при помощи Antora.

Anotra генерирует статичные сайты документации. Статичный сайт - это простой HTML-сайт, созданный без лишней сложности, без CMS и движка.

Для создания сайтов можно использовать стандартные стили или изменить их под себя. На мой взгляд настроить пользовательский интерфейс сайта при помощи Antora значительно легче, чем настроить внешний вид документа при экспорте из чистого AsciiDoc. Чтобы настроить сайт, нужны всего лишь навыки HTML и CSS, чтобы настроить конвертер AsciiDoc, потребуется владеть навыками программирования.

Это технически сложная тема, здесь я никому не отдам балл, потому что желаемой простоты нет ни в AsciiDoc, ни в DITA.

В идеале я бы хотел, чтобы в обоих случаях настроит внешний вид результата было так же просто, как с Antora, только общедоступные навыки. Счёт не меняется.

DITA:AsciiDoc 4:5

Обратная совместимость

Что я имею в виду под "обратной совместимостью" и почему это важно? Вот, например, когда разработчик языка разметки добавляет новую функцию, допустим появился новый конвертер или новая функция синтаксиса. Мне всегда хочется испытать новые возможности и применить их в продукте. Хочется обновиться, но получится ли сохранить обратную совместимость с существующими решениями, вот в чём вопрос.

DITA

Обычно новые функции DITA оперативно добавляют в новые версии DITA OT. Но проблема в том, что новые версии  DITA OT не очень задумывают о поддержке предыдущих пользовательских решений. То есть существующие плагины для DITA OT предыдущей версии могут не поддерживаться в новой версии.

В таком случае вы будете поставлены перед выбором: обновить DITA OT и собственный плагин или остаться на предыдущей версии и не получить новую фичу. Захотите ли вы снова проходить через огонь, воду и XSL-трансформации.

AsciiDoc

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

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

DITA:AsciiDoc 4:6

Техническая поддержка

DITA

И последний важный пункт. У DITA нет как таковой технической поддержки. Такое ощущение, что её разрабатывают таинственные люди в капюшонах за закрытыми дверьми в подвалах. Можно получить помощь от таких же любителей DITA на StackExchange или спросить на форуме Oxygen, где скорей всего ответят, но без гарантий.

AsciiDoc

У AsciiDoc всегда невероятно крутая поддержка. Спросить совета можно в чате AsciiDoc, на GitHub или даже в твиттере.

Такие же любители AsciiDoc или сам разработчик языка разметки обязательно помогут. Не знаю, когда спит разработчик AsciiDoc. За это докину ещё один балл.

DITA:AsciiDoc 4:7

Итог

AsciiDoc и DITA имеют примерно сопоставимые возможности, во многом AsciiDoc выигрывает, но в других моментах DITA предоставляет гораздо больше возможностей.

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

Выбирать инструмент всего стоит с умом, принимать взвешенные решения. Если вы планируете переход на Docs as Code, выбирайте не DITA или AsciiDoc, взвесьте все за и против, изучите функции одного и каждого языка разметки. Усложнение не всегда хорошо, как не очень хорошо и упрощение, выбирайте то, что подходит вам.