Комментарии 17
Уважаю такой труд! Спасибо, что поделились. Мы сейчас пробуем создать связку из Sphinx+Latex>PDF человекочасов действительно нужно много), решили что слишком затратно для того, чтобы готовить на проект 4-5 вордовских документов.
Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.
Не очень понятно, почему не в MS Word сразу? Шаблоны для документации наверняка можно найти или купить недорого. И заказчик был бы доволен.
Средств для автоматического создания файлов в таком формате тоже вроде хватает...
Ну как это непонятно
1) для ворда нужна винда или мак которых чаще всего под рукой нет
2) автоматизировать и/или версионировать doc/docx отдельная боль
3) конвертировать во что-то кроме pdf или html тоже боль
В этом плане asciidoc и latex (да даже пресловутый markdown) на голову выше ворда
Например для некоего абстрактного сервера документооборота (ну или, попросту, архива документов).
Если лениво — прикрутите к ворду git, он (git) сам всё сделает.
Или не сделает? Или не прикрутите?
2. С версионированием и контролем изменений у Word беда. Кто тот или иной текст засунул в документацию? В связи с какими изменениями в коде засунул? Хотя сравнение документов (именно конечных форматов) — прекрасная функция
3. Ну и с автоматическим созданием тоже всё не очень хорошо. Asciidoc, Markdown, rst создается из чего угодно (это же текст), а вот Word далек не из чего угодна. Сама задача сложнее
С версионированием и контролем изменений у Word беда. Кто тот или иной текст засунул в документацию?
А чем плох такой вариант, через TortoiseGit?:
А в том, чтобы содержание этого файла можно было настраиваемым образом использовать в других документах. Этого у Word нет.
Понятно, если надо отчётные формы помещать в документацию, то придется это делать скриптом, там, через автоматизацию Word.
Нет, я сам внутреннюю документацию предпочитаю в .md или .archimate. Но вот недавно сдавали этап сертификации во Франции, несколько десятков документов — так делали через Google Doc. Совместная работа, комментарии, можно озадачить конкретного человека конкретной строкой, принять/отвергнуть изменения. Потом все это выгружается в .docx или .pdf. Хотя вот историю смотреть тяжело, конечно.
Вариант хорош. И обязательно нужен, но для сравнения выпущенных версий документов. Скажем, согласовали какую-то инструкцию. Потом выпустили новую версию и можем указанным Вами образом сравнить. Pdf-документы так удобно сравнить не получится.
А вот для работы над документацией этот вариант просто очень громоздок. Насколько проще работать с таким видом. Тут и изменения в коде, и связанные изменения в документации, причём сразу во всех файлах.
Аналогично через автоматизацию Word можно сделать всё, но сложно или долго. А в Asciidoc простая директива include.
Вопросы же простые. Мы делаем документ или документацию? Наша документация будет жить вместе с продуктом или сделали и забыли?
В случае md, adoc всё достаточно тривиально
Пока не будет создан нативный конвертер в docx <...> или, <...> odt
Но ведь есть различные конвертеры типа pandoc, которые совместно с ним же и конвертируют в другие форматы, например, doc/docx, pdf.
Мне кажется, правильнее было бы сказать конвертер из doc/docx/odt обратно в asciidoc. Внутри своей команды вы можете легко всем этим управлять, но когда документ выходит на утверждение/согласование — обычно это doc/docx. А потом он возвращается с правками, которые надо применить, а потом закоммитить. И при этом изменения коммитов должны касаться только правок. Разве не так?
Кроме Pandoc я, честно говоря, других конвертеров не знаю. Pandoc имеет смысл только для помощи в ручной конвертации документа. На выходе Pandoc не выдает качественного документа, поддерживающего всю разметку Asciidoc (точнее Docbook, потому что прямое применении Pandoc к Asciidoc — это кошмар), а также рамки и тому подобную ерунду. Pandoc + доводочные костыли — так себе решение — прыжок без парашюта. И как бы Pandoc не развивался, он всё прогоняет через AST, т.е., вспоминая Форда, машина может быть любого цвета, если этот цвет — чёрный. Отсюда и вывод о необходимости именно нативного легко расширяемого конвертера.
Насколько я понимаю Вашу мысль, хорошо бы сделать обратный конвертор, который после внесения правок автоматизирует их утрамбовку обратно в Asciidoc (автоматическая генерация коммитов — было бы верхом красоты). Но документ в doc/docx/odt получается из объединения многих Asciidoc-документов. А часто (в нашем случае), изменения надо вносить в исходный код, если, например, в документе размещены атрибуты REST-интерфейса в табличной форме. Скорее нужно говорить о том, чтобы легко понять, куда вносить правки. Думаю, это тоже решаемый вопрос при использовании нативного конвертера с сохранением определенной мета-информации в результирующем документе. Ну и отсюда уже можно думать что-то на тему автоматических коммитов.
Да. Вы верно понимаете.
Исходный "код" документа находится в команде, на выходе получается красивый, скопилированный doc/docx/odt, годный для чтения.
Читатели (руководство, заказчики) читают "красивый" документ, вносят правки, комментарии, возвращают в команду. И теперь стоит задача, "декомпилировать" правленный документ в исходники, но так чтобы были внесены только правки (что-то удалили, что-то добавили, что-то исправили, или, дополнительно, что-то прокомментировали).
Команда принимает во внимание комментарии, принимает правки, возможно, вносит доп.правки, сохраняет и генерироует новый документ.
Когда-то давно я задумывался можно ли это сделать с помощью markdown, но быстро понял, что с ним не получится. Возможно asciidoc или другой формат в этом плане лучше.
Но мне видится еще проблема таблиц с многострочными текстами в ячейках. Кажется, ни один из форматов такого не поддерживают.
Таблицы — вопрос решенный. Вот пример таблиц в Asciidoc:
Можно и многострочные заголовки делать. И вложенные таблицы. И даже повторять на каждой странице только номера столбцов.
Процесс тоже более менее понятен (при наличии нативного экспорта в doc/docx/odt):
Вопрос в инструменте, который поможет вносить обратные правки. Что это такое может быть? Вот тут хорошо бы порассуждать.
Само сравнение, как справедливо указано здесь, сделать просто.
Понятно также, что мы работаем с текстом, т.е. поиском найти, куда вносить изменение, можно довольно быстро. Но явно тут можно найти что-то более красивое и не очень сложное.
Почему рецензирование не может проходить в том же git-репозитории? Doc-review-as-code-review?
Если так возможно, самый лучший вариант. Но есть целый ряд ситуаций, когда рецензировать необходимо или просто желательно именно конечный документ. Например
Сложная структура документации. Скажем, у нас очень много документации, сгенерированной автоматически из кода по различного рода DSL'ям/тестам. Да даже если просто активно используются инструменты single source -- вставка, профилирование, переменные (атрибуты) и т.п.
Согласование документации может проходить в системах документооборота, туда же не засунешь репозиторий.. а то и несколько. Хотя, теоретически, возможно и даже хорошо, но я не знаю реальных реализаций
Свои статьи и различные документы пишу в Asciidoc'е, но на рецензирование обычно всегда рассылаю в Word'е/Google'е/OD. Это просто удобнее, пусть все прекрасно владеют и гитом, и Asciidoc'ом
На самом деле с момента написания статьи много воды утекло. Теперь проблема обратных правок более менее понятна, по крайней мере, в случае с Asciidoctor'ом
Asciidoc для подготовки сложной документации