Docs-as-Code в технической документации: переход от reStructuredText к AsciiDoc

[ElDark]

Интересно, поддержка конвейера и базы документации в итоге осуществляется девопсерами или вы взяли это на себя?

[Basis_Habr]

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

[Kuendr]

Переход на AsciiDoc выглядит реально выгодным, особенно для интеграции с GitLab. А вы рассматривали другие форматы, например Markdown, перед выбором AsciiDoc? Если да, почему остановились именно на нем?

[Basis_Habr]

Markdown рассматривали, но по рекомендации DevOps-коллег остановились на AsciiDoc.

[alexs963]

Потом захотите совсем отделить содержание от внешнего вида и перейдёте на TeX или typst.

[Basis_Habr]

А в чем преимущество typst перед Markdown или AsciiDoc?

[alexs963]

Всё что угодно будет лучше md, на более-менее сложных документах. Typst я не трогал особо, потыкал на их сайте примеры и всё. Его привел как аналог TeX. Преимуществом TeX будет наличие стилей, которые могут кардинально поменять внешний вид документа без изменения содержимого. Но в случае AsciiDoc наверное это можно решить применением css при экспорте в html.

[saamich]

А нашли способ как это все меньшими усилиями в docx перегонять?

[Basis_Habr]

Потребности конвертировать из AsciiDoc в DOCX у нас не возникало, поэтому специально поисками инструментов не занимались. Посмотрели несколько вариантов для себя, но всерьез вопрос не изучали. Заказчикам передаем документы в формате PDF, их устраивает.

[samd]

Прошу прощения, но три раза перечитал статью, но так и не смог найти упоминания о том, как формируется итоговый документ pdf. Или у вас иная задача?

[Basis_Habr]

Финальный PDF формируется в рамках CI/CD-конвейера с помощью asciidoctor. Стили документа задаются в отдельном JSON-файле в VSCodium.

[ValentinaLemiakina]

Спасибо за отличную статью!

1. Если получится, напишите пожалуйста подробнее от "картах документа", которые вы готовили на этапе перехода от RTS к AsciiDoc, пункт 3. Это список всех имеющихся документов по определенным темам/фильтрам?

2. Правильно ли сказать, что ваш переход к AsciiDoc с RTS это старт с уже более продвинутой позиции, чем если переходить с продуктов MS Office? И стоит ли пройти через этап работы с языками разметки или возможно сразу идти к AsciiDoc, минуя RTS ?

[Basis_Habr]

1. Карта документа - это файл main.adoc, где мы прописываем заголовки, нумерацию глав, аппендиксы, медиа, в общем, все, что мы хотим видеть внутри документа. Потом при генерации PDF документ собирается в соответствии с этой картой. Список всех документов формируется в зависимости от потребности самой компании, какие документы она хочет писать в формате AsciiDoc. Тут нет правил, компания сама составляет список, дает названия и т.д.

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