Если картинок немного, то проще сразу нарисовать

Через "что-то подобное" точно можно. Если язык позволяет вручную расставлять элементы. Тот же Pikchr.

https://pikchr.org/home/doc/trunk/doc/examples.md

О, класс, спасибо

Но я не сказал, что будет легко! :)

О! спасибо!

Да, мы мучались-мучались, но пришли к тому же выводу. Просто вручную очень лень.

Мы у себя хорошо набили руку рисовать подобное в Inkscape. Прямоугольники с текстом, стрелки, привязки. Всё быстро и понятно.

plantuml имеет прям большой смысл, когда есть много входных данных, типа диаграмм классов. Потому как с большими объёмами текста в графических редакторах уже не так весело.

а мы рисуем в drawio. делает двухслойный файл, так что можно открыть для просмотра в почте как png

После возни с Docs as Code рисование мышкой в граф. редакторе, похоже, воспринимается уже почти как откровение ;)

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

поэтому делают один раз перед сдачей.

для меня, как для человека из продуктовой компании слово «перед сдачей» означает «за два дня до увольнения» =)

В идеальном мире и модель архитектуры описывается в каком-нибудь Structurizr еще до написания кода, а потом эта модель постоянно поддерживается в актуальном состоянии :)

ты очень молодец. поражаюсь твоей последовательности в вопросах DocOps

или в  Enterprice Architecht

ой, у меня тут коллега техпис после моего доклада о том, как мы переехали на openapi и _наконец-то_ смогли подойти к тому, что бы по-настоящему внедрить doc-first выдала совершенно восхитительный вопрос от которого сама что-то для себя интересное узнала:

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

какая няшная штука, спасибо за наводку.

Не за что! Кстати, такие инструменты — тоже не предел того, что можно сделать. Еще до ажиотажа с "as Code" существовали подходы Model Driven Development/Architecture. Вот там, судя по всему, был практически достигнут идеал для исполняемой/автоматической документации.

только не дешевая

Только в очень ограниченном наборе задач. Но общее движение верное. Может, чуть преждевременно. Какой бы хороший код ни был, всё равно нужны средства его наглядного представления.