В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.
Года полтора назад мы втянулись в проект по разработке небольшой отраслевой информационной системы. По этой небольшой системе необходимо было разработать с полсотни взаимоувязанных документов и согласовать их не меньше, чем с сотней человек.
Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc (https://asciidoctor.org/). Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.
Пройдя определённую боль, мы с коллегами решили ей поделиться.
Но сначала о хорошем.
- Получилось.
- Переиспользование содержания (а его было много) позволило обеспечить согласованность документов. Функции Asciidoc в части переиспользования абсолютно не уступают DITA. Это важно, когда разные документы согласуют более ста специалистов и изменения должны отражаться в большом количестве документов.
- Текстовый поиск позволил быстро ориентироваться в массиве исходных текстовых данных.
- Условная компиляция включать/не включать данные ДСП (для служебного пользования) позволяет упросить согласование документов в рабочем порядке.
- Asciidoc мы активно используем для генерации документации. Например, для генерации отчётных форм внутри решения мы используем тот же Asciidoc. Таким образом, эти отчётные формы мы можем автоматически помещать в документацию. Также прекрасно работает генерация документации на API (REST, SOAP), СУБД, процессы согласования (с помощью PlantUML) и т.п. Автоматически создавать документацию из тестов еще не получилось, но вот здесь получилось https://habr.com/ru/company/alfa/blog/454720/, большое спасибо авторам за данную статью.
Так в чём же боль? Их всего две:
- внешний вид получаемых печатных форм документов;
- процесс согласования.
Сначала о внешнем виде печатных форм документов. Asciidoc поддерживает несколько вариантов генерации печатных документов.
- Нативный https://github.com/asciidoctor/asciidoctor-pdf. Проект недостаточно гибкий, чтобы чувствовать себя свободно.
- Почти нативный https://github.com/Mogztter/asciidoctor-web-pdf – лучшее решение, если выходной документ должен иметь сложную верстку. Но с точки зрения создания документов есть проблемы. Например, с переносом таблиц со страницы на страницу.
- Использование Pandoc для экспорта в docx, или odt (через Docbook, т.к. напрямую из asciidoc работает вообще никак). Поддержка docx и odt – это здорово. Но вопрос в ее качестве. Писать костыли и настраивать документ с помощью макросов или sdk – крайне сложно и ненадёжно. И всё равно надо помнить, какие возможности Asciidoc можно использовать, какие нельзя. А какие можно, но в конкретном случае всё же нельзя.
- Старый способ через Docbook – docbook-xsl. Да, docbook-xsl – это тяжело. Но мы его как-то настроили. Результат здесь https://github.com/CourseOrchestra/course-doc. Именно этот способ мы и выбрали.
- Вариант Docbook – TeX, для бесстрашных и неограниченных по ресурсам.
Также нужно отметить, что Asciidoc не поддерживает заголовок таблиц из нескольких строк и стили для ячеек, что в некоторых случаях непреодолимо. Поэтому нам помогли вот с таким проектом https://github.com/CourseOrchestra/asciidoctor-plugins (спасибо, Гийом).
Вторая проблема – согласование документов. Согласуем мы не репозиторий, а конкретные документы. И тут выяснилось, что заказчик привык к MS Word для работы с текстовыми документами и знать не хочет о внесении правок в pdf. Более того, все правки заказчик требует в виде изменений в MS Word в режиме рецензирования.
Как-то удалось всё же упросить работать с pdf. А сравнение версий мы решили сделать с помощью вот этого проекта https://github.com/JoshData/pdf-diff. Если применить следующее преобразование в ImageMagick, на выходе получаем красивый pdf.
pdf-diff before.pdf after.pdf -t 7 -b 92| docker run -i dpokidov/imagemagick png:- -crop 294:207 -border 1x% +repage pdf:- > comparison_output.pdfВсё это не очень хорошо работает на таблицах с заголовками, поскольку повторяющиеся заголовки на каждой странице pdf-diff воспринимает как изменения, если таблица просто сместилась. Также при сравнении альбомных страниц результат получается неудобочитаемым. И вишенка на торте. После подготовки документов всё равно пришлось вручную переводить некоторые из них в MS Word. Для этого мы конвертировали Asciidoc в html и немного доформатировали. Так себе развлечение.
Выводы
- Asciidoc подходит для проектов, где требования к документации высоко формализованы. Можно даже сказать, что использование специальных систем подготовки документации на основе открытых форматов типа Asciidoc, DITA, Docbook, reStructuredText, Markdown для таких проектов безальтернативно.
- Пока не будет создан нативный конвертер в docx (Open XML) или, что правильнее, в odt (Open Document) описанная технология будет оставаться уделом энтузиастов.
