This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control".
> content can quickly become as complex as regular code
Okay, but has that actually happened in practice?
Before we built Markdoc, our documentation was powered by ERB (embedded Ruby templates). Having content mixed with arbitrary code made it incredibly hard to reason about either. Because Markdoc is a declarative language rather than imperative, there's no intermediate state to keep track of, making things easier to follow.
At Stripe, both engineers and tech writers contribute to documentation. Markdoc makes things easier for everyone by keeping the content separate from the code, while still making it possible to build more interactive experiences when you want to. (For example, our integration builder [0] is also powered by Markdoc.)
MDX, which allows embedding JSX isn't fully declarative, since arbitrary imperative structures can be used in JS blocks in JSX.
Reasons we treat docs like code
Coders and writers have borrowed tools and techniques from each other for decades. When you look at the history of producing docs and code together, you see that tools were invented specifically to produce docs while coding.
For example, the JavaDoc tool has been available since the first Java release in 1999. Visualizing the code in HTML, providing accessible online docs, and updating the documentation with the code were all keys to its success.
I don't think you have to choose between "can be powerful" and "can be simple."
If you want to lock things down so no one EVER puts code in your docs, Markdoc looks great.