В Q1 2023 дошли, наконец, руки и до проектной документации. Для этого, правда, пришлось договориться с командой не только о том, что документация это first-class citizen, но и придумать как держать её в актуальном состоянии без усложнения рабочего цикла. Конечно, у нас есть Confluence. Более того, мы обязаны вести документацию в Confluence, потому что “так надо” с точки зрения бизнеса для cross-team knowledge sharing и вот это всё. С другой стороны, я ненавижу душный Confluence и мне кажется, что это нормально. В этом плане, у нас в команде полное взаимопонимание. К тому же, документация в Confluence всегда отстаёт от жизни. Следить за её актуальностью как бы надо бы регулярно, но для этого нужен какой-то особый уровень дисциплины, а мы тут про реальные вещи говорим. Хочется держать полную документацию со всеми C4 и прочими диаграммами поближе к коду, в репозитории проекта. Изменение должно версионироваться и проходить review, так же как и код. Диаграммы должны быть, по большей части, декларативными, поэтому завозим Mermaid. Хотелось бы D2, но уже в другой раз. Sphinx выглядит старо, a его RST-формат громоздко, все хотят Markdown. Берём mkdocs и наряжаем в mkdocs-material с расширениями. Во, теперь классно. И с Mermaid он дружит из коробки, cool. Дополнительно добавляем mkdocstrings для интроспекции и ещё пару свистелок. Объявляем make docs с hot reload и наслаждаемся красотой. Локально. А как же Confluence? Тут уже пришлось заморочиться и запилить решение, которое рендерит нужные нам markdown в html, а потом с помощью lxml приводит его к формату, который нравится Confluence, учитывая все его фирменные xml-based macros. Готового полного решения, увы, не нашлось. После чего загружаем документ и сопутствующие attachments через API ну и остаётся прикрутить весь этот процесс к CI/CD, чтобы документация публиковала себя самостоятельно сразу после попадания в master. Получилось достаточно удобно и решило большую часть первоначальных проблем.