Concordo contigo. "Uma imagem vale mais do que mil palavras" não atoa. E realmente um diagrama muitas vezes podia ter me economizado umas boas horas (inclusive já tive que fazer um diagrama pra um sistema legado e explicar num onboarding). Eu vou ser sincero e dizer que a melhor forma de fazer isso de forma sustentável a longo prazo é algo "dentro da máquina", ou seja, no próprio código. Mas eu entendo que arquitetura não é clara dentro do código, então precisaria de alguma outra forma de colocar isso que possa ser atualizada corriqueiramente sem gastar tempo.
Já existem soluções de documentação de APIs via comentários, talvez alguma configuração em arquivos de pacotes (toml, package.json e afins) ou uma centralização com ADRs. Mas a sua alternativa é muito interessante e a meu ver quebra um galho de forma razoável