Всем привет.

Попал на большой проект. Несколько сервисов, у них есть плагины, есть горизонтальное масштабирование (реплики, баланс), свои утилиты, интеграция с внешними системами. Сложная система развертывания, частично ansible, частично свои скрипты. Базы данных: есть Postgres, есть MongoDB, есть S3. REST, gRPC.
В общем, много всего, как "в ширину", так и "в глубину".

Работаю в проекте уже почти год, успешно выполняю задачи (не по всей системе), но никак не могу охватить всё это целиком. Для этой цели хотелось бы "написать книгу о проекте", такую, чтобы человек со стороны, квалифицированный, но не знакомый с системой, мог относительно быстро в ней разобраться.

Есть, конечно, вики на проекте, но она не покрывает всё, сведения отрывочные, да и написано так, что помочь она может в основном тому, кто уже всё знает, но что-то забыл. Например, заходишь в раздел с каким-то достаточно общим названием — а там несколько скриптов для консоли, и всё.

Вот как бы структурировать это всё в документации? Может быть, есть шаблоны описания архитектуры с разделами и подразделами (ну кроме ГОСТа на информационные системы )?
Или какие-то книги известных авторов с описаниями похожих по сложности систем, из которых можно было позаимствовать оглавление?

Здравствуйте, dmitry_npi, Вы писали:

_>Вот как бы структурировать это всё в документации? Может быть, есть шаблоны описания архитектуры с разделами и подразделами (ну кроме ГОСТа на информационные системы )?

C4 же https://habr.com/ru/articles/778726/

_>Или какие-то книги известных авторов с описаниями похожих по сложности систем, из которых можно было позаимствовать оглавление?
Проблема в том, что линейное описание для системы не подходит. В линейном описании сложно выразить глубокую структуру и связи между элементами. Фактически роль линейного описания выполняет сам текст программ. А то что невыразимо в тексте нужен графический инструмент.

Здравствуйте, dmitry_npi, Вы писали:

_>Вот как бы структурировать это всё в документации? Может быть, есть шаблоны описания архитектуры с разделами и подразделами (ну кроме ГОСТа на информационные системы )?
_>Или какие-то книги известных авторов с описаниями похожих по сложности систем, из которых можно было позаимствовать оглавление?

Скормить всё ChatGPT (коммерческому, у него больше контекст и кол-во токенов), попросить дать новое оглавление и реструктуризацию.

Здравствуйте, gandjustas, Вы писали:

G>C4 же https://habr.com/ru/articles/778726/

С4 позволяет описывать только структуру (статику). Нужно добавить описание динамики, очень верхнеуровнево.
В виде списка функциональных требований и sequence или dataflow diagram основных процессов

Здравствуйте, dmitry_npi, Вы писали:

_>Есть, конечно, вики на проекте, но она не покрывает всё, сведения отрывочные, да и написано так, что помочь она может в основном тому, кто уже всё знает, но что-то забыл. Например, заходишь в раздел с каким-то достаточно общим названием — а там несколько скриптов для консоли, и всё.

Так по идее и должно быть, когда не было цели дефрагментировать и дополнить знания. Чтобы решить этот вопрос нужна база знаний. А это приводит к пониманию, что у любых знаний есть автор.

База знаний.
1. Личная.
2. Коллективная.

Личная база знаний имеет одного автора. Коллективная база знаний состоит из множества фрагментов каждый из которых имеет одного автора.

В коллективной базе знаний разные люди могут вносить правки во фрагменты до высокой степени смешения, но всё равно у каждого нового символа есть автор. Скопированные символы сохраняют старого автора.

Условно можно разделить содержимое именованных глав и подглав, статей, веб-страниц на.
1. Навигационные структуры.
2. Полезное содержимое.

Пример.

категория-1 / категория-10 / содержимое-7548

тег-45, тег-89

Оглавление
0. Категории.
1. Раздел-1.
2. Раздел-2.
3. Литература.

Категории
 признак 1
  содержимое-7597
  содержимое-9499
 признак 2
  содержимое-3574
  содержимое-5692

Раздел 1.

Содержимое содержимое содержимое содержимое содержимое гиперссылка-5976 содержимое содержимое.

Раздел 2.

Содержимое содержимое содержимое гиперссылка-3569 содержимое содержимое.

Литература
 признак 1
  гиперссылка-4629
  гиперссылка-6396
 признак 2
  гиперссылка-8539
  гиперссылка-8469

предыдущее / следующее

1. Внешняя навигация уже открытых категорий.
2. Внешняя навигация тегами.
3. Внутренняя навигация оглавлением.
4. Внешняя навигация перехода на категории.
5. Внутреннее содержимое по разделам с внешней или внутренней навигацией по гиперссылкам.
6. Внешняя навигация очерёдностью.

Смысл здесь в том, что не получится сразу создать подходящую навигационную последовательность, понадобятся правки. Причём как и содержимое навигация имеет автора.

Отсюда же вытекает вывод, что тем же веб-страницам выгоднее присваивать номера, чтобы при смене названий не бились ссылки.

А дальше многократно заполняешь примерно такой шаблон попутно наращивая знания.

Что касается баз знаний, то это обширный вопрос. Кто-то даже зарабатывает большие деньги обучая других.

Другое дело практика. По сути чтобы признать идею успешной нужна реально работающая система на изложенных авторами принципах.