Спасибо за статью. Самые ценные статьи/доклады -- про то, что не получилось, а не про то, что получилось.
Требования к системе документирования, приведенные в начале статьи, скорее ближе к wiki/confluence-подобным системам. Docs-as-code тут будет проигрывать. Понятно, все можно докрутить/перекрутить, но мы же всегда боремся со сложностью.
Если бы были требования к использованию автогенерации (когда из кода мы получаем артефакты, переиспользуемые в документации) и/или к тестированию документации (автоматизированные подходы к обеспечению ее качества), тогда можно было бы побороться за Docs-as-code. Опять же, уже в wiki/confluence этого также можно добиться, но тут уже в них сложностей будет больше.
Самая большая сложность Docs-as-code -- это, безусловно, согласование конечной документации (речь идет именно о сложной документации). Наиболее эффективный вариант здесь, кажется, -- это генерация выходного файла (файлов) в формате текстового процессора google docs/word/writer. Текстовые процессоры более менее нормально дифуют версии и позволяют удобно предлагать правки. Вы, кстати, могли бы дифовать pdf'ы, хотя это работает значительно хуже.
В любом, случае, классно, что есть статья, которая убережет от использования Docs-as-code там, где есть лучшие альтернативы.
Обратное тоже справедливо, во многих проектах Аджаил работает. Причем проблема Аджаил-проекта может быть либо в том, что подход действительно не подходит, либо в том, что его нужно по-другому применять. Лично мне Аджайл комфортен (если убрать радикальные трактовки), поэтому, кажется, любые исследования на тему развития подхода можно только приветствовать.
Если так возможно, самый лучший вариант. Но есть целый ряд ситуаций, когда рецензировать необходимо или просто желательно именно конечный документ. Например
Сложная структура документации. Скажем, у нас очень много документации, сгенерированной автоматически из кода по различного рода DSL'ям/тестам. Да даже если просто активно используются инструменты single source -- вставка, профилирование, переменные (атрибуты) и т.п.
Согласование документации может проходить в системах документооборота, туда же не засунешь репозиторий.. а то и несколько. Хотя, теоретически, возможно и даже хорошо, но я не знаю реальных реализаций
Свои статьи и различные документы пишу в Asciidoc'е, но на рецензирование обычно всегда рассылаю в Word'е/Google'е/OD. Это просто удобнее, пусть все прекрасно владеют и гитом, и Asciidoc'ом
На самом деле с момента написания статьи много воды утекло. Теперь проблема обратных правок более менее понятна, по крайней мере, в случае с Asciidoctor'ом
Подарок прекрасен, я сам был бы ему так рад, так рад))), но, как видно из предыдущих комментариев, такой подарок -- редкость при решении сложных бизнес-задач. Как исполнитель, приступая к решению, мы только примерно знаем, "ЧТО" будем создавать.
Конкретно проекты, подвигшие меня на эту статью, -- это проекты с гос/окологос структурами (44-ФЗ, 223-ФЗ,..., усугубленные 248-ФЗ).
ORM/миграции -- вроде бы узкий вопрос. Но организация хранилищ данных в условиях постоянных изменений настолько важна, что я привел наше конкретное базовое решение, которое облегчает жизнь. Помимо Java-проектов у нас есть python-проекты, тут мы используем in-memory SQLite для тестирования, но отсутствие идемпотентных миграций особенно на ранних стадиях, на которых мы много работаем с заказчиком и многое меняем (сделал->увидел->понял-> много раз в цикле) очень неудобно, накапливается много ненужных миграций. Также инкрементные миграции -- значит всегда один ответственный за структуру БД, т.е. бутылочное горлышко. Для обхода этих ограничений в не-Java проектах мы даже выкрутили https://github.com/CourseOrchestra/2bass.
Подход DDD делает все элементы создаваемой системы, в первую очередь функциональные, прозрачными для участников, также упрощает документирование. В хаосе начала проекта это важно.
Понятно, что ORM (точнее, в общем случае, подход к организации работы с хранилищем данных) и DDD -- вопросы из разных областей. Но, с точки зрения важности для проекта, решения об их использовании находятся на одном уровне значимости.
Это точно. Мне, правда, только один раз удалось участвовать в проекте, где руководитель был прямо заинтересован в результате проекта. Было здорово. Обычно же есть какое-то головное подразделение со стороны заказчика, которое всеми правдами и неправдами выстраивает работу с другими участниками, в т.ч. ИБ, инфраструктурой. Причём у всех подразделений свои руководители, цели и задачи.
По поводу Agile. На таких проектах интуитивно хочется уйти от Agile. Хочется сначала найти точки согласования. Но в моей практике удалось сдвинуть несколько проектов с десятками заинтересованных лиц. Как только люди чётко видят свою зону ответственности и ее наполнение, они успокаиваются и начинают быть конструктивными.
С CI-CD не совсем понял комментарий, почему архитектор не нужен. По опыту, как только CI/CD начинает быть регулярным (например, два раза в сутки) сразу становится легче взаимодействовать с заинтересованными лицами и узлы проекта начинают развязываться на глазах. Возможно, мне везло, но этот процесс всегда удавалось выстроить вопреки, а не благодаря заказчику.
Помимо удобного ревью разработчиком я бы назвал еще
Обновление документации может входить в definition of done
Править документацию быстрее, т.к. она лежит в том же проекте
Ну и, конечно, документация в коде сама по себе создает условия для применения процедур автоматического обеспечения/контроля актуальности.
Те же скриншоты у нас тоже сначала лежали в LFS-ной папочке. Потом, кстати, долго медитировали надо опытом Akita. И в конце родилась идея с URL. Причём родилась она сначала не для документации, а для упрощения тестирования и улучшения UX. Вообще, возник хороший принцип -- не принимать никаких архитектурных решений исключительно ради документации, но при оценке архитектурных решений учитывать критерий документируемости
Спасибо за статью. Действительно при всех плюсах документация очень медленно переползает в исходники и действительно есть объективные причины, которые медленно преодолеваются.
Именно вопрос скриншотов нам в некоторых проектах удалось решить по-другому. Всё равно конечный продукт (back+front) собирается в CI и всё равно e2e тесты бегают. Достаточно добавить тесты, которые создают автоматические скриншоты. У нас есть требование, чтобы все окна, требующие скриншот в документации, вызывались через URL. Поэтому на выходе работает всего один простой параметризованный тест. Понятно, всё равно могут быть бинарные файлы (например, какой-нибудь мем в документации.. meme as code пока вроде не придумали), тогда да, LFS.
Вопрос ревизии MR, кстати, тоже можно решить. Достаточно на этапе сборки MR собрать выходной документ и сравнить с выходным документом предыдущей версии основной ветки. А файл сравнения уже будет содержать не текстовой diff, а diff выходного документа с картинками, форматированием, зачеркиваниями, отчеркиваниями и всем, всем, всем.
Кстати, в тему совместной работы надо обязательно упомянуть. У LibreOffice Writer есть один значимый для многих недостаток. При сравнении документов, если LO находит различие в таблице, он показывает, что вся таблица удалена и новая таблица добавлена. Microsoft Word корректно отмечает изменение внутри таблиц. Насколько помню, issue в LO висит очень давно.
Точно, сам же пробовал. Обычно просто Google Docs используем.
Документ с «Microsoft does not recommend or support server-side Automation of Office» относится, в том числе, к офису 365 (есть в перечне версий, возможно вы кнопочку "Моre..." не нажали). Тут речь идёт не о наличии/отсутствии инструментов, а о рисках и о поддержке. Сама автоматизация прекрасно работала и до 2010 года и этим активно пользовались. И есть прекрасные проекты, которые запускают Office на сервере (https://gitlab.iaaras.ru/iaaras/gostdown). Читал, что Office даже докеризуется.
Всё верно, вариантов много. И действительно "не рекомендуется и не поддерживается" не значит "запрещается". Безусловно, экосистема Microsoft Office прекрасна (иначе бы не использовали). Тем не менее в поддержке серверной автоматизации пока есть пробелы. О них Microsoft честно говорит и, где возможно, предлагает пути обхода.
Изначальный тезис был о том, что Word/Excel в разы мощнее Writer/Calc. Как минимум, если сравнивать Word и Writer, есть значимые задачи, где Writer показывает себя лучше.
По поводу совместного редактирования речь шла о решении Collabora Office (https://github.com/CollaboraOnline/online), а не о встроенных возможностях совместного редактирования в десктопном продукте. Их у Microsoft, по-моему, вообще нет. Могу ошибаться, но все участники совместной работы с документом Microsoft Word должны использовать веб-версию.
По поводу серверного использования.
"Microsoft does not recommend or support server-side Automation of Office" означает "не рекомендует и не поддерживает".
При этом unattended лицензия действительно есть. Я это понимаю следующим образом, лицензия дает возможность использовать Microsoft Office в отсутствие конечного пользователя, но ничего не гарантирует.
Как метко выразились в комментарии ниже, суть этой лицензии в том, что она "не запрещает".
Я говорю только про текстовые процессоры (word/writer). Calc/Excel -- отдельная тема.
Если используется SharePoint, то, конечно, Word. Однако с совместным редактированием документов LibreOffice проблем нет. В любом случае согласитесь, отсутствие поддержки автоматизации Word на сервере -- это минус экосистемы Microsoft Office, где-то маленький, где-то большой.
Отсюда Microsoft does not recommend or support server-side Automation of Office.
Альтернативы решают те или иные проблемы, но полность функциональность Microsoft Word не перекрывают.
Серверная RPA -- термин неверный. По вашей ссылке используется термин Unattended RPA. Цитата из данного документа:
Although Microsoft 365 for unattended RPA provides a license that enables the automation of Office with no user present, all current versions of Office were designed and tested to run as end-user products on a client workstation with a user present to interact with the application’s interface.
В наших проектах это означает нельзя. Наверняка есть проекты, где можно.
Как человек, работающий с Word с 1994 и силою обстоятельств столкнувшийся с LibreOffice Writer, это не совсем точно. Огромной проблемой LibreOffice Writer является типографика внутри таблиц и раскладка сложных таблиц. Но у Word свои минусы. Здесь указано, что Microsoft Office нельзя использовать на сервере. Огромный минус в качестве экосистемы. Linux+Libreoffice, очевидно, экономичнее, чем Windows+Microsoft Office просто за счёт ОС. По скорости работы с большими документами разницы не замечал. Есть более мелкие вещи, что-то лучше в Word, что-то – во Writer. На текущий момент Word и Writer – сравнимые продукты при условии одинакового уровня подготовки пользователей.
По поводу проверок. Поскольку мы не понимаем, в каком контексте мы вставляем файл, то и проверить отдельно мы его не можем. Скажем, во вставляемом файле помещён абзац. Если в родительском файле директива include приклеена к другому абзацу, вставляемый абзац вольется в родительский, если отклеена, то станет отдельным абзацем. Если линтер настроен, например, на максимальный размер абзаца в предложениях, то придётся всегда проверять конечный файл.
По поводу тэгирования исходного кода: директиву tag как комментарий можно вставить в исходный код в любом языке программирования. Причём этот код может быть тестируемым. Т.е. мы точно уверены в том, что вставляемый код работает.
С автогенерацией проблема в смешивании синтаксиса и вставляемых полей. Скажем, я автогенерирую описание СУБД и у меня в какое-то поле таблицы asciidoc должно попасть описание поля, но разработчик в комментарии начал это описание с вертикальной черты: таблица слетит. Я могу закодировать символы, но тогда я лишусь возможности в комментариях использовать синтаксис asciidoctor. С XML такой проблемы нет.
Спасибо за статью. Хотел добавить моменты, которые, правда, на счёт не влияют:
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 -- в части редактирования, контроля версий. Объединить бы
Идея в другом. Есть эксплуатационная документация. Есть её элементы, которые описывают текущее состояния информационной системы. Тут возможны три случая.
Лучший вариант -- автоматическая генерация.
Если автоматическая генерация невозможна, придумываем критерии, которые просигнализируют, что документацию (возможно) надо менять. Оцениваем трудозатраты на такие изменения.
Если критерия нет, или предполагаемые затраты на актуализацию слишком высокие, значит не документируем.
В нашем упрощенном случае (если я содержательно правильно понял предложенную ситуацию) можно в баш добавить
df --output=source,target | grep убрать что-то сиюсекундное >> mynote.txt
Я бы воспринимал это следующим образом.
Документация -- это не конкретная схема или документ, но весь проект (в нашем случае -- код), обеспечивающий актуальность, достоверность и полноту выходных документов.
В этом смысле регресса документации не было. Она была недостаточно хороша, и не дала возможности поймать подключение SSD.
Вот если бы мы подключили ещё SSD или что-то аналогичное и опять бы его прошляпили, это было бы уже регрессом.
Точно так же, как с приложением. Выявили ошибку, заткнули регрессионным тестом.
Спасибо за статью. Самые ценные статьи/доклады -- про то, что не получилось, а не про то, что получилось.
Требования к системе документирования, приведенные в начале статьи, скорее ближе к wiki/confluence-подобным системам. Docs-as-code тут будет проигрывать. Понятно, все можно докрутить/перекрутить, но мы же всегда боремся со сложностью.
Если бы были требования к использованию автогенерации (когда из кода мы получаем артефакты, переиспользуемые в документации) и/или к тестированию документации (автоматизированные подходы к обеспечению ее качества), тогда можно было бы побороться за Docs-as-code. Опять же, уже в wiki/confluence этого также можно добиться, но тут уже в них сложностей будет больше.
Самая большая сложность Docs-as-code -- это, безусловно, согласование конечной документации (речь идет именно о сложной документации). Наиболее эффективный вариант здесь, кажется, -- это генерация выходного файла (файлов) в формате текстового процессора google docs/word/writer. Текстовые процессоры более менее нормально дифуют версии и позволяют удобно предлагать правки. Вы, кстати, могли бы дифовать pdf'ы, хотя это работает значительно хуже.
В любом, случае, классно, что есть статья, которая убережет от использования Docs-as-code там, где есть лучшие альтернативы.
Обратное тоже справедливо, во многих проектах Аджаил работает. Причем проблема Аджаил-проекта может быть либо в том, что подход действительно не подходит, либо в том, что его нужно по-другому применять. Лично мне Аджайл комфортен (если убрать радикальные трактовки), поэтому, кажется, любые исследования на тему развития подхода можно только приветствовать.
Если так возможно, самый лучший вариант. Но есть целый ряд ситуаций, когда рецензировать необходимо или просто желательно именно конечный документ. Например
Сложная структура документации. Скажем, у нас очень много документации, сгенерированной автоматически из кода по различного рода DSL'ям/тестам. Да даже если просто активно используются инструменты single source -- вставка, профилирование, переменные (атрибуты) и т.п.
Согласование документации может проходить в системах документооборота, туда же не засунешь репозиторий.. а то и несколько. Хотя, теоретически, возможно и даже хорошо, но я не знаю реальных реализаций
Свои статьи и различные документы пишу в Asciidoc'е, но на рецензирование обычно всегда рассылаю в Word'е/Google'е/OD. Это просто удобнее, пусть все прекрасно владеют и гитом, и Asciidoc'ом
На самом деле с момента написания статьи много воды утекло. Теперь проблема обратных правок более менее понятна, по крайней мере, в случае с Asciidoctor'ом
Тут необходимо уточнение (в понимании, конечно, что RST/Sphinx -- один из однозначных лидеров Docs as Code).
(1) Asciidoc'у не чужда i8n. https://docs.fedoraproject.org/en-US/docs/ (Fedora) использует https://po4a.org/. https://inponomarev.ru/corejava (курс по Java, слайды созданы с помощью asciidoctor-revealjs) использует http://docs.translatehouse.org/projects/translate-toolkit/en/latest.
(2) Community Asciidoc (субъективно, конечно) очень развито и на любой вопрос найти/получить ответ можно достаточно быстро
Подарок прекрасен, я сам был бы ему так рад, так рад))), но, как видно из предыдущих комментариев, такой подарок -- редкость при решении сложных бизнес-задач. Как исполнитель, приступая к решению, мы только примерно знаем, "ЧТО" будем создавать.
Конкретно проекты, подвигшие меня на эту статью, -- это проекты с гос/окологос структурами (44-ФЗ, 223-ФЗ,..., усугубленные 248-ФЗ).
ORM/миграции -- вроде бы узкий вопрос. Но организация хранилищ данных в условиях постоянных изменений настолько важна, что я привел наше конкретное базовое решение, которое облегчает жизнь. Помимо Java-проектов у нас есть python-проекты, тут мы используем in-memory SQLite для тестирования, но отсутствие идемпотентных миграций особенно на ранних стадиях, на которых мы много работаем с заказчиком и многое меняем (сделал->увидел->понял-> много раз в цикле) очень неудобно, накапливается много ненужных миграций. Также инкрементные миграции -- значит всегда один ответственный за структуру БД, т.е. бутылочное горлышко. Для обхода этих ограничений в не-Java проектах мы даже выкрутили https://github.com/CourseOrchestra/2bass.
Подход DDD делает все элементы создаваемой системы, в первую очередь функциональные, прозрачными для участников, также упрощает документирование. В хаосе начала проекта это важно.
Понятно, что ORM (точнее, в общем случае, подход к организации работы с хранилищем данных) и DDD -- вопросы из разных областей. Но, с точки зрения важности для проекта, решения об их использовании находятся на одном уровне значимости.
Это точно. Мне, правда, только один раз удалось участвовать в проекте, где руководитель был прямо заинтересован в результате проекта. Было здорово. Обычно же есть какое-то головное подразделение со стороны заказчика, которое всеми правдами и неправдами выстраивает работу с другими участниками, в т.ч. ИБ, инфраструктурой. Причём у всех подразделений свои руководители, цели и задачи.
По поводу Agile. На таких проектах интуитивно хочется уйти от Agile. Хочется сначала найти точки согласования. Но в моей практике удалось сдвинуть несколько проектов с десятками заинтересованных лиц. Как только люди чётко видят свою зону ответственности и ее наполнение, они успокаиваются и начинают быть конструктивными.
С CI-CD не совсем понял комментарий, почему архитектор не нужен. По опыту, как только CI/CD начинает быть регулярным (например, два раза в сутки) сразу становится легче взаимодействовать с заинтересованными лицами и узлы проекта начинают развязываться на глазах. Возможно, мне везло, но этот процесс всегда удавалось выстроить вопреки, а не благодаря заказчику.
Помимо удобного ревью разработчиком я бы назвал еще
Обновление документации может входить в definition of done
Править документацию быстрее, т.к. она лежит в том же проекте
Ну и, конечно, документация в коде сама по себе создает условия для применения процедур автоматического обеспечения/контроля актуальности.
Те же скриншоты у нас тоже сначала лежали в LFS-ной папочке. Потом, кстати, долго медитировали надо опытом Akita. И в конце родилась идея с URL. Причём родилась она сначала не для документации, а для упрощения тестирования и улучшения UX. Вообще, возник хороший принцип -- не принимать никаких архитектурных решений исключительно ради документации, но при оценке архитектурных решений учитывать критерий документируемости
Спасибо за статью. Действительно при всех плюсах документация очень медленно переползает в исходники и действительно есть объективные причины, которые медленно преодолеваются.
Именно вопрос скриншотов нам в некоторых проектах удалось решить по-другому. Всё равно конечный продукт (back+front) собирается в CI и всё равно e2e тесты бегают. Достаточно добавить тесты, которые создают автоматические скриншоты. У нас есть требование, чтобы все окна, требующие скриншот в документации, вызывались через URL. Поэтому на выходе работает всего один простой параметризованный тест. Понятно, всё равно могут быть бинарные файлы (например, какой-нибудь мем в документации.. meme as code пока вроде не придумали), тогда да, LFS.
Вопрос ревизии MR, кстати, тоже можно решить. Достаточно на этапе сборки MR собрать выходной документ и сравнить с выходным документом предыдущей версии основной ветки. А файл сравнения уже будет содержать не текстовой diff, а diff выходного документа с картинками, форматированием, зачеркиваниями, отчеркиваниями и всем, всем, всем.
Кстати, в тему совместной работы надо обязательно упомянуть. У LibreOffice Writer есть один значимый для многих недостаток. При сравнении документов, если LO находит различие в таблице, он показывает, что вся таблица удалена и новая таблица добавлена. Microsoft Word корректно отмечает изменение внутри таблиц. Насколько помню, issue в LO висит очень давно.
Точно, сам же пробовал. Обычно просто Google Docs используем.
Документ с «Microsoft does not recommend or support server-side Automation of Office» относится, в том числе, к офису 365 (есть в перечне версий, возможно вы кнопочку "Моre..." не нажали). Тут речь идёт не о наличии/отсутствии инструментов, а о рисках и о поддержке. Сама автоматизация прекрасно работала и до 2010 года и этим активно пользовались. И есть прекрасные проекты, которые запускают Office на сервере (https://gitlab.iaaras.ru/iaaras/gostdown). Читал, что Office даже докеризуется.
Всё верно, вариантов много. И действительно "не рекомендуется и не поддерживается" не значит "запрещается". Безусловно, экосистема Microsoft Office прекрасна (иначе бы не использовали). Тем не менее в поддержке серверной автоматизации пока есть пробелы. О них Microsoft честно говорит и, где возможно, предлагает пути обхода.
Изначальный тезис был о том, что Word/Excel в разы мощнее Writer/Calc. Как минимум, если сравнивать Word и Writer, есть значимые задачи, где Writer показывает себя лучше.
По поводу совместного редактирования речь шла о решении Collabora Office (https://github.com/CollaboraOnline/online), а не о встроенных возможностях совместного редактирования в десктопном продукте. Их у Microsoft, по-моему, вообще нет. Могу ошибаться, но все участники совместной работы с документом Microsoft Word должны использовать веб-версию.
По поводу серверного использования.
"Microsoft does not recommend or support server-side Automation of Office" означает "не рекомендует и не поддерживает".
При этом unattended лицензия действительно есть. Я это понимаю следующим образом, лицензия дает возможность использовать Microsoft Office в отсутствие конечного пользователя, но ничего не гарантирует.
Как метко выразились в комментарии ниже, суть этой лицензии в том, что она "не запрещает".
Я говорю только про текстовые процессоры (word/writer). Calc/Excel -- отдельная тема.
Если используется SharePoint, то, конечно, Word. Однако с совместным редактированием документов LibreOffice проблем нет. В любом случае согласитесь, отсутствие поддержки автоматизации Word на сервере -- это минус экосистемы Microsoft Office, где-то маленький, где-то большой.
Тут важна точность формулировок.
Отсюда Microsoft does not recommend or support server-side Automation of Office.
Альтернативы решают те или иные проблемы, но полность функциональность Microsoft Word не перекрывают.
Серверная RPA -- термин неверный. По вашей ссылке используется термин Unattended RPA. Цитата из данного документа:
Although Microsoft 365 for unattended RPA provides a license that enables the automation of Office with no user present, all current versions of Office were designed and tested to run as end-user products on a client workstation with a user present to interact with the application’s interface.
В наших проектах это означает нельзя. Наверняка есть проекты, где можно.
Как человек, работающий с Word с 1994 и силою обстоятельств столкнувшийся с LibreOffice Writer, это не совсем точно. Огромной проблемой LibreOffice Writer является типографика внутри таблиц и раскладка сложных таблиц. Но у Word свои минусы. Здесь указано, что Microsoft Office нельзя использовать на сервере. Огромный минус в качестве экосистемы. Linux+Libreoffice, очевидно, экономичнее, чем Windows+Microsoft Office просто за счёт ОС. По скорости работы с большими документами разницы не замечал. Есть более мелкие вещи, что-то лучше в Word, что-то – во Writer. На текущий момент Word и Writer – сравнимые продукты при условии одинакового уровня подготовки пользователей.
По поводу проверок. Поскольку мы не понимаем, в каком контексте мы вставляем файл, то и проверить отдельно мы его не можем. Скажем, во вставляемом файле помещён абзац. Если в родительском файле директива include приклеена к другому абзацу, вставляемый абзац вольется в родительский, если отклеена, то станет отдельным абзацем. Если линтер настроен, например, на максимальный размер абзаца в предложениях, то придётся всегда проверять конечный файл.
По поводу тэгирования исходного кода: директиву tag как комментарий можно вставить в исходный код в любом языке программирования. Причём этот код может быть тестируемым. Т.е. мы точно уверены в том, что вставляемый код работает.
С автогенерацией проблема в смешивании синтаксиса и вставляемых полей. Скажем, я автогенерирую описание СУБД и у меня в какое-то поле таблицы asciidoc должно попасть описание поля, но разработчик в комментарии начал это описание с вертикальной черты: таблица слетит. Я могу закодировать символы, но тогда я лишусь возможности в комментариях использовать синтаксис asciidoctor. С XML такой проблемы нет.
Спасибо за статью. Хотел добавить моменты, которые, правда, на счёт не влияют:
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 -- в части редактирования, контроля версий. Объединить бы
Идея в другом. Есть эксплуатационная документация. Есть её элементы, которые описывают текущее состояния информационной системы. Тут возможны три случая.
Лучший вариант -- автоматическая генерация.
Если автоматическая генерация невозможна, придумываем критерии, которые просигнализируют, что документацию (возможно) надо менять. Оцениваем трудозатраты на такие изменения.
Если критерия нет, или предполагаемые затраты на актуализацию слишком высокие, значит не документируем.
В нашем упрощенном случае (если я содержательно правильно понял предложенную ситуацию) можно в баш добавить
Я бы воспринимал это следующим образом.
Документация -- это не конкретная схема или документ, но весь проект (в нашем случае -- код), обеспечивающий актуальность, достоверность и полноту выходных документов.
В этом смысле регресса документации не было. Она была недостаточно хороша, и не дала возможности поймать подключение SSD.
Вот если бы мы подключили ещё SSD или что-то аналогичное и опять бы его прошляпили, это было бы уже регрессом.
Точно так же, как с приложением. Выявили ошибку, заткнули регрессионным тестом.