Agreed with your point of accessibility to people who don't live in the code.

But that doesn't preculude documentation near code nor Markdown. It just means that you need a CI job to publish the doc stored in the git repo as (for example) HTML or PDF.

For diagrams stuff like PlantUML are great, edit as text, publish as images.