[Анализ и проектирование систем, Подготовка технической документации] Asciidoc для подготовки сложной документации
Автор
Сообщение
news_bot ®
Стаж: 6 лет 9 месяцев
Сообщений: 27286
В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 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) описанная технология будет оставаться уделом энтузиастов.
===========
Источник:
habr.com
===========
Похожие новости:
- [Анализ и проектирование систем, Читальный зал] Успеть за 24 часа: история переезда оборудования между ЦОДами
- [Java, Анализ и проектирование систем, Lisp, Проектирование и рефакторинг, Конференции] Effective Programs (10 Years of Clojure) — Rich Hickey (с русским переводом) (перевод)
- [Программирование, Анализ и проектирование систем, Проектирование и рефакторинг, Микросервисы] Разложение монолита: Декомпозиция БД (часть 2)
- [Анализ и проектирование систем, Работа с 3D-графикой, CAD/CAM] Средства моделирования крупных сборок: хорошие новости для производителей промышленного оборудования
- [Анализ и проектирование систем, Аналитика мобильных приложений, Конференции, Дизайн] Как мы делали SM Lab Analyst Day — первый митап по системной аналитике в Sportmaster Lab (+ видео всех докладов)
- [Программирование, Анализ и проектирование систем, Проектирование и рефакторинг, Микросервисы] Разложение монолита: Декомпозиция БД (часть 1)
- [Программирование, Анализ и проектирование систем, IT-инфраструктура, Носимая электроника] Аналитика событий на опасном производстве, или зачем «Цифровому рабочему» Kafka, Esper и Clickhouse
- [Подготовка технической документации] Коммуникация: как понимать друг друга даже на удаленке
- [Анализ и проектирование систем, Проектирование и рефакторинг, CAD/CAM, Инженерные системы] 10 главных усовершенствований в SOLIDWORKS Electrical 2021
- [Тестирование IT-систем, Тестирование веб-сервисов, Подготовка технической документации] State & Transition Diagramm — что это и как применять
Теги для поиска: #_analiz_i_proektirovanie_sistem (Анализ и проектирование систем), #_podgotovka_tehnicheskoj_dokumentatsii (Подготовка технической документации), #_dokumentatsija (документация), #_gost (ГОСТ), #_asciidoctor, #_asciidoc, #_proektirovanie_sistem (проектирование систем), #_analiz_i_proektirovanie_sistem (
Анализ и проектирование систем
), #_podgotovka_tehnicheskoj_dokumentatsii (
Подготовка технической документации
)
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 18:03
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 9 месяцев |
|
 В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования. Года полтора назад мы втянулись в проект по разработке небольшой отраслевой информационной системы. По этой небольшой системе необходимо было разработать с полсотни взаимоувязанных документов и согласовать их не меньше, чем с сотней человек. Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc (https://asciidoctor.org/). Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось. Пройдя определённую боль, мы с коллегами решили ей поделиться. Но сначала о хорошем.
Так в чём же боль? Их всего две:
Сначала о внешнем виде печатных форм документов. Asciidoc поддерживает несколько вариантов генерации печатных документов.
Также нужно отметить, что 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 и немного доформатировали. Так себе развлечение. Выводы
=========== Источник: habr.com =========== Похожие новости:
Анализ и проектирование систем ), #_podgotovka_tehnicheskoj_dokumentatsii ( Подготовка технической документации ) |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 18:03
Часовой пояс: UTC + 5