So with Rust's RFCs, which I think are close enough to what you're talking about to count, we recently made a change that I feel has drastically improved the quality of the actual text. This happened recently, so we don't have a ton of experience, but I'm liking what I've seen so far.
For some history, a while back we introduced a "How do I teach this" section. So basically, in the RFC, you're supposed to describe how we'd go about explaining these changes to anyone who is not a compiler hacker. This was a good idea, but people would often just write "stuff gets added to the book and API docs" and leave it at that.
So to fix this: rust-lang/rfcs#2059
Basically, a TL;DR of this change is: You start off a proposal by writing it as though it was something that exists and explain it to someone who knows Rust, but not this change. Then, after that, you go back and explain it at a sort of "reference-level", that is, the super-low-level details.
I've found that this framing is way more helpful for understanding; you get a high-level overview at first, and then only after you've got the big picture do you dive into the small. In some ways this is related to "README driven development" where you imagine the API first, and then go and implement it.
I don't know if that's helpful, but maybe some food for thought.