звучит как субъективное мнение относительно конфлюенса, но вопрос: зачем сверху инструмент, если у вас уже есть такой для решения?

Лично мне аутсорс не нравится по одной причине: интересы моего работодателя и заказчика зачастую разные. Особенно если заказчик хочет разовый проект.
В итоге на словах меня нанимают решить проблему заказчика как можно эффективней, а на деле где-то через 2-3 уровня вверх от меня люди балансируют между тем чтобы часов побольше продать, но при этом и клиент ± довольный остался, а отдуваться за это всегда приходится рядовому и линейному составу.

При этом мне кажется что, например, джунам поработать в аутсорсе и набраться в опыте самое оно.

Ну просто интересно, есть ли какие-то еще варианты.

так вставляйте ссылки на него, кто же вам мешает? ))
не понимаю вас

там есть diagram.io встроенный плагин если вам надо будет в процессе строить диаграммы, ссылки можно делать и вставлять... у мен на проекте архитектор спокойно пользуется

Кажется, что документация процесса должна быть как раз подальше от кода, а не поближе к нему

» Лично мне аутсорс не нравится по одной причине: интересы моего работодателя и заказчика зачастую разные. Особенно если заказчик хочет разовый проект.

Я вам открою тайну, но в коллективе, где N>1 человека, тоже всегда N или больше интересов. Причем зачастую противоположных.
И в продуктовой разработке ровно также приходится кого-то удовлетворять, иногда наступая на свои интересы.

Согласен, просто мой опыт был таким что в аутсорсе я чаще с этим сталкивался, поэтому недолюбливаю)

мне кажется, что нам всё равно нужны точные определения

Плюсану

Что такое документация процесса? Это то же,  что я спросил: словари терминов, потоки данных, сервисы и фичи ?

У вас есть процесс(ы) (последовательная смена состояний) и это фактически описание взаимодействия элементов вашей ИС. Документация это описание требуемых взаимодействий (спецификация) или имеющихся (реализация). Описывать реализацию обычно не имеет смысла, потому что реализация а) описана в "коде" б) постоянно меняется.

Все что вы перечислили по идее находится на разных уровнях абстракции и соответственно на разных схемах. Если вам знакомы понятия "уровень абстракции" и "инкапсуляция", то никаких значительных проблем с пониманием, какие схемы вам нужны и какие инструменты помогут вам эти схемы сделать с наименьшими затратами, быть не должно.

Диаграммы можно нарисовать используя вот эту модель. Оттуда достаточно 2-ух уровней. Остальное как правило избыточно.
Рисовать можно с помощью PlantUML. Тогда можно будет сгенерить картинки в любом формате, будь то svg или png или даже ASCII.
Описывать все можно или в Wiki или в репозитории (А лучше в Wiki которая под капотом и есть репозиторий,  который записать что то можно не только руками а и программными средствами).

- Соответсвенно общую картинку рисуем и расписываем в репозитории Wiki.
- Отдельные компоненты документируем на уровне репозиториев этих компонентов (В README и комментариями в коде).
- Далее проходим по всем репозиториям, генерим оттуда документацию в Wiki формате и пишем ее в Wiki репозиторий.
- После этого из Wiki генерим нужное представление и публикуем его как статический сайт.

У меня есть гипотеза, что чем проще инструмент в использовании для редактирования информации, совместной работы и визуального оформления этой информации. (Confluence, Notion, etc.), тем быстрее документация превращается в плохо структурированную мусорку с кучей устаревшего хлама.

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

Короче говоря Notion, Confluence и т.п. на мой взгляд отличные системы для коллаборативной работы над документами, но отвратнейшие системы для работы с документацией. Все что я видел всегда eventually в таких системах превращалось в мусорку по которой потом надо ходить и "Гуглить" чтобы хоть что-то найти. Зато красиво и с фентифлюшками.

Другими словами: Git + "Diagrams as a Code" tool + Wiki + Static Site Generator. самое то.

Confluence (+ pluntUML) - хороший вариант, один из лучших.
Но есть варианты:
git+asciidoc+pluntuml+куча магии: позволяет делать красивую документацию по коду, но обсуждать будет сложно и через PRы.
neo4j - позволяет играть с разными viewpoint и автоматически заполнять данными, но без текстов
Ну и есть "взрослые" средства описания архитектуры, но это очень дорого и почти никогда не нужно.

Так кто мешает по свагеру делать странички в конфлюенсе?

У статического сайта есть, увы, критический недостаток - там очень сложно выстраивать обсуждение и комментирование.
И сложно делать "быстрые правки", а они нужны.
В любом случае за документацией по архитектуре кто-то должен следить (архитектор, техлид или кто-то про разработчиков хотя бы)

Плагин PlantUML для Confluence ущербен к сожалению 😔 Плохая реализация хорошей идеи.

ущербен, да. но держите рецепт: вставляем диаграмму картинкой и рядом в code-block текст макроса