Подход единого источника спецификаций

Проблематика

и подход были неплохо сформулированы в 2015 году техническими писателями docvision. Основные возможности, которые нужны как поставщику документации, так и ее потребителю:
1. Простое версионирование изменений в виде plain text diff'ов.
2. Простой merge изменений
3. Возможность проведения процедуры согласования изменений (aka merge request review)
4. Наличие движка для рендера в html для простоты чтения и [возможно] индексирования
5. Наличие возможности определить актуальна ли спецификация, относительно определенного стенда.
6. Возможность переиспользования ресурс-файлов для документации в проекте приложения

Разметка как инструмент

Исторически сложилось, что лидерами индустрии для решении озвученных проблем были разметки DITA (как было упомянуто ранее в статье) и DocBook (подробнее об использовании). Однако, разметка не упрощалась, а программисты за 10-15 лет подкинули простым смертным такие вещи как MarkDown, AsciiDoc, и reStructuredText (кстати авторка довольно крутой взяла слоган у немцев, но странные конвейеры для работы)

Markdown

Среди 3х лидеров современности стоит сразу вычеркнуть md. Он слишком маленький, многие крупные компания пытаются его кастомизировать, писать свой туллинг для рендера или даже для конвейера. Но это не имеет смысла, так как подобный инструментарий уже написан для остальных языков разметки.
Он не смог шагнуть дальше, чем readme для репозитариев, что бы было что показать в Visual Studio Code плагинах.

AsciiDoc

А, лучше упоминать его новую имплантацию AsciiDoctor - это md на стероидах, сравните сами. Большая часть синтаксиса не только унаследована, но и развита для сложных случаев форматирования, например, отдельный букв в слове. Но куда важнее, что он поддерживает множество расширений.
Начать стоит с языков описания диаграмм таких как dot, plantUml и остальных менее популярных. Продолжить можно такими расширениями как reveal-js, Asciidoctor Liquibase, cukedoctor, reveal-js.

presentatoin-mode

Если в голом виде AsciiDoctor - замена MS word, то вместе с reveal-js - как быстрая и простая альтернатива pptx и на keenote (Однако развесистые диаграммы развертывания для мидл- и топ-менеджмента по-прежнему удобнее рисовать в pptx)

Liquibase

Asciidoctor Liquibase в паре с plantUml создана для визуализации изменений ER-диаграмм. Проект очень свежий, еще мало отзывов и найденных багов.

cucumber

Cukedoctor призван решить проблему раздельного хранения и использования тест-кейсов и системной спецификации. Идеология проекта: они должны дополнять друг друга и ускорять погружение при достаточном уровне сопровождения как кейсов, так и спек.

confluence

Отдельно стоит упомянуть бурно развивающийся плагина de.docs-as-co.publishToConfluence композитного конвейера docToolchain от создателей arc42.org.
Эти инженеры подошли к проблеме сбора лучших паттернов проектирования системных спецификаций и архитектурных артефактов в 2012. И [видимо] под давлением гибких методологий сместили фокус с Enterprise Architect в сторону конвейера спецификаций, но с более слабыми связями между объектами ИС. Именно эта группа инициативных инженеров собирали шаблоны описания ентерпрайз проектов на EA, word, adoc, писали свой конвейер и именно они стали основными идеологами фразы doc-as-code, которых теперь цитируют.

reStructuredText

Если присмотреться на разметку RST, то легко находится популярный конвейер sphinx, который изначально использовался в основном для сборки документации и доставки ее до хостинга readthedocs.
Из-за того, что конвейер основан на python, то он так же является расширяем и многие уже опубликвали свои плагины, как "публикация на github pages" так и даже "публикация на confluence".
Однако последний посыл выглядит сомнительным, несмотря на заявление поддержки версии конфли 6.7+, так как обычно монолитные плагины часто ломаются. Даже при поддержке версии confluence внутри мажорной версии 6.
Так же есть неприятная мелочь, в январе 2020 закончена поддержка py27 и практически все зависимости на этой версии или ломаются или многократно напоминают о необходимости обновления. Думаю, через несколько кварталов все значимые пакеты портируют либо мейнтейнеры, либо сопереживающие. Но пока так.
В совокупности этих факторов сложности и неопределенности ни эта разметка и этот конвейер не может рекомендоваться к использованию в совместной работе. В соло – вполне может быть и стоит попробовать. Вот только не понятно для чего.