Не знал, что PlantUML способен отображать фазы луны )))
Ой... это же док опс... не бейте за ошибку в слове moon! ))

Ого, сколько полезняшек по гиту накидали! Спасибо всем огромное!

Спасибо!

Так как в чате техписов меня благополучно проигнорировали, то вот

Поговорим про ревью при docs-as-code подходе?

Как осуществить код ревью исходников - понятно, но когда отдаёшь собранное (ведь оно нагляднее и не все смогут исходники прочитать, особенно если это не маркдаун, а разметка посерьёзнее), то фидбек приходит в не самом удобном виде (комменты в личку или на почту, тикеты в трекере), который в разы уступает тому же комментированию в гугле, например. Есть ли у современных генераторов режим сборки “на ревью”, который сохраняет ассоциации с исходниками, например, даёт возможность ревьеру оставлять комменты на блоках текста и генерит патч с комментами, которые накатываются на исходники и ты уже проходишь по ним. Неплохая фантазия? Что-то подобное есть? Может, кто-то использует какой-то иной подход? Или для подобного ревью ничего не придумано?

> который в разы уступает тому же комментированию в гугле, например.

в видели как в гитлабе комментируются MR?

Я не хотел обидеть, но вы просто написали, что вам тоже интересно и повторили, что сейчас единственное что можно - это собрать и получить комменты в тикет)

Для внутреннего процесса ок, но каждому внешнему эксперту или клиенту объяснять, что такое MR в гитлабе - это утопия

Не видел, но подозреваю, что примерно как PR на гитхабе. А как это относится к вопросу “как удобно ревьюить не исходники, а собранный хелп”?

я не понимаю, что может делать клиент или внешний эксперт в этом процессе, поэтому сложно вам откомментировать

Мы DocOps'им тех.задание, а не справку, так что может не совсем подходящий кейс, но расскажу

Собираем docx Pandoc'ом, выгружаем в Google Docs, а потом ручками комментарии сопоставляем с исходником.
Внешнее ревью, получается, самое узкое место во всей цепочке, но плюсы DocOps'а в целом сильно перевешивают и заставляют кушать этот кактус

Очень хочется придумать или реализовать что-то умнее, руки не доходят

У нас не продуктовка просто

Источник инфы внешний, читатель внешний

Вот и мне хочется)

Обдумывал эту тему, больше всего для реализации не хватает подобия source maps для Markdown'а или RST

Для тех, кто не разработчик: source maps, это файлы с инфой для сопоставления исходника с компилированным/обфусцированным кодом для дебага.
На пальцах, как это работает в вебе.
1. В браузер клиенту уходит минифицированный JS
2. Там, допустим, поймали ошибку, отправили на сервер
3. На сервере сопоставили ошибку по source maps с исходником, разраб изучает ошибку не по дебрям собранного кода, а по исходнику

Мне кажется, если научить какой-нибудь Foliant выкидывать к собранному сайту source maps, дальше проблема решается первым попавшимся JS-скриптом для добавления комментов на произвольной HTML странице

Да, у меня именно такая мысль и была про дебаг-сборки, вдруг это где-то уже реализовано для докопсов…

Я не видел, но мог плохо искать.

В целом, задача на пару вечеров, надо только собраться и сделать.
@Nick_Volynkin как насчёт DocOps-хакатона?)

В тему сорс мапов было обнаружено следующее, попытка под markdown-it https://www.npmjs.com/package/markdown-it-source-map интересно только решён ли как-то сам сбор комментариев на страницах

И ещё мысль, что собирать комменты можно в GitHub issues, у них вроде неплохой API, https://docs.github.com/en/free-pro-team@latest/rest/reference/issues#comments  по сути нам из данных нужна строка исходника только, к которой оставлен коммент, но вот можно ли in-line