У нас конфигурация  продукта в YAML и нужно ее описывать параллельно с разработкой, да еще и иметь возможность это все выгрузить например в PDF для "органов".
Опыта такого нет, читаю синтаксис, смотрю примеры, но хотелось бы рекомендаций опытных ребят в этом вопросе.

не понимаю смысла документирования именно YAML
думаю, что в формате пояснительных записок к конфигурациям

Я тоже думаю, что это формат поясниельных записок. Уж не знаю, каких именно. Зависит от ваших задач. Если для "органов", то, наверное, нужен ГОСТ.

А вообще, в вашем случае этот процесс можно сколько-то автоматизировать. Написать (или найти) простой скрипт для формирования статьи или её скелета на основе предоставленного YAML-файла. Звучит интересно, да и руками переписывать доку при обновлении продукта не надо будет — на стадии активной разработки это частый кейс.

А если ещё YAML-файлы с комментарями от разработчиков, так это вообще огроменное поле для автоматизации:
Брать YAML, формировать из него тот же .md и отправлять в движок для документации типа sphinx-doc или pandoc (умеют генерить PDF). И на выходе получить практически готовую документацию.

вчера я не знала ответа на этот вопрос, но сегодня могу ответить - confluence серверный)

конфиги в YAML популярны у разных девопс-инструментов, можно подсматривать решения в них

https://docs.gitlab.com/ee/ci/yaml/
https://docs.travis-ci.com/user/tutorial/
https://docs.docker.com/engine/reference/builder/
https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#describing-a-kubernetes-object
https://docs.ansible.com/ansible/latest/user_guide/playbooks.html

У нас подключен Google Analytics и всю инфу и посещениях и конверсии тащим оттуда

идея неплохая

Write The Docs Portland 2020 пройдёт с 3-5 мая https://www.writethedocs.org/conf/portland/2020/

ты собираешься?

Возможно.

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

Это плагин. Но у нас Cloud, насколько я знаю в серверной тоже можно так сделать.

Например на маркетплейсе, что типа такого есть, но платное естественно.

А так можете в АУГ сходить спросить, там тоже подскажут https://t.me/augmoscow

спасибо!

Есть полезный бесплатный плагин
https://marketplace.atlassian.com/apps/1217079/page-view-tracker?hosting=server&tab=overview
Позволяет отслеживать количество просмотров страницы и пользователей, которые просматривали страницу. Конфигурируется в админке конфы очень просто.

да, такой уже есть, спасибо) хотелось бы более расширенный инструмент)

Бесполезный платный плагин 😂