Ultimately however, I'd expect to see just one page for each command. Not an 'official' version, and then the wiki version, but a single combined page. As you imply, what we really need is a means of pulling the wiki content wholesale into the bbdocs. Or vice versa?
You only problem I see here is that if half the docs are auto-generated and half are hand crafted, sanely combining and syncing the 2 could be tricky.
The in-source bbdoc stuff could be moved into the Wiki, but I'm a little nervous about this as I like having the minimalist, easy-to-use autodoc system in there - makes it much more likely that changes will actually get doced. Also, it's guaranteed to stay in sync.
The other option - moving the Wiki into the source code - is definitely a non-starter!
Personally, I don't think having 2 sets of docs is a big problem - one can be the terse, official documentation, the other can be more relaxed and tip-filled.
IDE's could selectively link to either the official docs or the Wiki docs, so the in-source stuff might eventually become irrelevant anyway. But I still like having it there as a 'backstop'.
We could 'prime' the Wiki with the current official docs and people can go nuts with it from there.
Sound sane?