Comments 15
Отличная статья, спасибо! Сам использую AsciiDoc, даже думаю собственный сайт перевести на Antora + AsciiDoc просто так ради забавы. На DITA, боюсь, так не получится.
Крайне странный выбор конкурента аскидоку. Обычно его сравнивают с restructuredtext или markdown. Про DITA - первый раз слышу. Держу пари он уступает даже latex-у по популярности.
Я не очень хорошо осведомлён о популярности разных инструментов. Могу судить по количеству вопросов на Stackoveflow:
dita: 298
asciidoc: 398
rst: 1182
latex: 9956
Если так посмотреть, то DITA и AsciiDoc примерно сопоставимы по популярности, а латексу в популярности уступают даже дита, аски и рст вместе взятые. Я в начале статьи говорил, что работал с дитой и с аски. Я не работал с рст или латексом, поэтому не могу сравнить с ним. Если вы работали и готовы написать статью, я с удовольствием прочитаю.
Если честно, не вижу препятствий, почему нельзя сравнивать диту и аски. И то и другое - инструмент для документации. Как видно из статьи, точки соприкосновения у них есть.
Маркдаун не сравнивал, потому что не вижу смысла. Его легче сравнить с MS Word. Могу сделать сравнение, в принципе, но это не очень интересно.
Как можно рассматривать xml-based (DITA) инструмент для работы в стиле Docs-As-Code? По моему опыту хранение таких документов в системе контроля версий и merge/разрешение конфликтов всегда дикая головная боль
А почему бы и нет? XML - это тоже код. Сколько работал с DITA в vcs, описанных вами проблем не испытывал. Конечно, работал один, но всё же.
Вот пример. Файлы проекта в visual studio (vcxproj) это xml файлы. Даже тривиальные изменения, когда 2 разработчика добавляют каждый по файлу в проект иногда приводят к merge-conflicts. Беда даже не в том, что нужно разрешать merge-conflicts - это нормальная рабочая ситуация. Сложности как у инструментов, так и у людей связаны с что происходит с xml-тегами. Они теряются, дублируются, перемещаются в неожиданные места. Наверняка часть проблем можно было бы избежать при определённом стандартном xml-форматировании. Например такой вариант был бы ещё ничего
<Source>File.txt</Source>Но, спасибо MS, там как-то так:
<Source>
File.txt
</Source>И вот когда независимо добавляются два таких блока, то часто конфликты разрешаются плохо (пример ниже). Тулы не понимают, что нужно рассматривать 3 добавленных строки как единый неделимый блок. Люди при ручном разрешении тоже часто ошибаются
// added by developer A
+<Source>
+ File1.txt
+</Source>
// added by developer B
+<Source>
+ File2.txt
+</Source>
// After conflict resolution
+<Source>
+ File1.txt
+ File2.txt
+</Source>
// What is needed
+<Source>
+ File1.txt
+</Source>
+<Source>
+ File2.txt
+</Source>
Если работать в одиночку и не вести параллельную разработку в параллельных ветках, то мне кажется, что почти всё равно что хранить. Даже docx кого-то устроит
Я так понимаю, этот пример из VSCode. В дитой таких проблем не замечал. У неё как раз регламентированная структура, всё довольно чётко.
В основном (на мой субъективный взгляд) docs as code инструменты выбирают ради единого источника. То есть в чём хранить есть разница, возможно как раз от Docx перешли.
Параллельная разработка документации - это для больших команд. Когда есть несколько техписателей. Но и в таком случае, мне кажется, случаи, когда разные люди в разных ветках делают один и тот же документ будут редкими. Они несомненно будут, но редко. И наверняка в таком случае в команде должны быть установлены алгоритмы действий.
У нас документацию пишут разработчики (asciidoc), поэтому весь инструментарий отточен - git, winmerge/kdiff/..., code reviews/pull requests/feature branches. Приятная особенность asciidoc, то что можно сконцентрироваться только на тексте (особенно при code review) и привычные инструменты работы с кодом отлично справляются.
Готов поверить на слово, что dita удобней других xml-based форматов. Просто намучались мы с проектными файлами в Microsoft Visual Studio (не VSCode) и другими xml исходниками, так что инстинктивно хочется держаться подальше
У нас внутреннюю документацию для разработчиков тоже пишут в asciidoc, точнее пишет один человек. Хотелось бы больше, но разработчики не очень хотят писать документацию.
Если код и документация хранятся в одном месте, то AsciiDoc однозначно будет удобнее для этих целей, чем DITA.
Какими редакторами пользуетесь для создания asciidoc?
Не нахожу в своих csproj чего-то вроде:
<Source>
File.txt
</Source>XML не очень хорошо мержится, это да, например resx у нас все-время конфликтит. Но проблемы с проектными файлами у нас не такие большие, как Вы описываете. Может Вы работали со старыми версиями студии, мы ведем активную разработку в разных ветках, и мерж проектных файлов не вызывает такой боли, чтобы думать об отказе от них.
Спасибо за статью. Хотел добавить моменты, которые, правда, на счёт не влияют:
conref и include работают по-разному. Include работает на низком уровне (до синтаксического парсера) и не позволяет проводить контроль консистентности на уровне вставки. В этом смысле conref лучше (хотя разговоры в Asciidoctor о создании confref-подобной директивы ведутся). Но (возможно я не прав) conref не позволяет вставлять тэгированные комментариями куски кода. Если так, это очевидный недостаток.
Я бы отличал конвертеры, которые сделаны в эко-системе Asciidoctor https://docs.asciidoctor.org/asciidoctor/latest/convert/custom/ (аналогичные есть для js и java) и конвертеры, реализующие собственные механизмы парсинга, тот же Pandoc или po4a. Нативные конвертеры обладают очень хорошими механизмами создания и расширения, это на голову лучше, чем XSLT. Можно ли ещё проще? По-моему, Фаулер, лет 20 назад написал статью о том, что XSLT не нужен, а паттерн Visitor вполне себе удобен в ruby (сейчас уже и практически во всех языках). Я пока не вижу течений, из которых можно предположить, что через 20 лет конвертер Asciidoctor будет интуитивней и без "извращенных" навыков. Но хотелось бы
XML -- это сила DITA -- в части автогенерации, автоматической обработки. Текстовый маркап -- сила Asciidoctor -- в части редактирования, контроля версий. Объединить бы
Не вникал в детали принципа работы, к сожалению, об этом сказать ничего не могу. Насчёт контроля консистентности - всё так. Но в AsciiDoc, вроде бы, и нет необходимости в контроле, потому что позволено вставлять всё и всюду. Есть редкие исключения, но вот так навскидку не вспомнить.
По поводу вставки тэгированных кусков кода не совсем понял. Куски кода вставлять можно. А специально тэгировать их нет необходимости, достаточно у каждого элемента создать уникальный ID.
Но больше всего меня обижает, что conref не вставит другой conref. То есть в источнике заимствования не должно быть заимствований. Include прекрасно справляется с инклудом инклуда.
Полностью согласен. Хотелось бы чего-то проще, но и так лучше, чем XSLT)
AsciiDoc тоже умеет автогенерацию, например, из javadoc, с помощью Antora. Не пробовал, но в далеко идущих планах испытать. Всё же AsciiDoc предлагает большой выбор уже готовых решений, которые можно повторить или использовать.
По поводу проверок. Поскольку мы не понимаем, в каком контексте мы вставляем файл, то и проверить отдельно мы его не можем. Скажем, во вставляемом файле помещён абзац. Если в родительском файле директива include приклеена к другому абзацу, вставляемый абзац вольется в родительский, если отклеена, то станет отдельным абзацем. Если линтер настроен, например, на максимальный размер абзаца в предложениях, то придётся всегда проверять конечный файл.
По поводу тэгирования исходного кода: директиву tag как комментарий можно вставить в исходный код в любом языке программирования. Причём этот код может быть тестируемым. Т.е. мы точно уверены в том, что вставляемый код работает.
С автогенерацией проблема в смешивании синтаксиса и вставляемых полей. Скажем, я автогенерирую описание СУБД и у меня в какое-то поле таблицы asciidoc должно попасть описание поля, но разработчик в комментарии начал это описание с вертикальной черты: таблица слетит. Я могу закодировать символы, но тогда я лишусь возможности в комментариях использовать синтаксис asciidoctor. С XML такой проблемы нет.
Сравнение возможностей AsciiDoc и DITA