There’re two entirely different problems I want to solve.
The first is that I want to integrate the docs with the code more. As is, there is no good way to tie docs to a given release version and no good way to make code + docs changes (so we forget the latter). This is all for me. If I could expect API changes to also change the relevant docs in the same PR, and then later do a
git diff v1.0.0..v1.5.0 -- docs/rest/ that would be hugely helpful to me.
The second is that we don’t get a lot of “external” contributions, in my opinion. There are probably lots of reasons for this and I can’t know them all, but the docs being tricky to get your head around as a newbie can’t help the situation. Currently the README talks about a weird compilation process and tools and the docs are in an odd format (that I’ve personally grown to dislike, too). I suspect a more Wiki-like approach here would help. A WYSIWYG editor probably wouldn’t hurt but I don’t think it’s essential either.
I was thinking GitBook might solve both these things in one change. I’m not necessarily convinced that’s the case any more, but those are the problem statements.