I'm good with all of your thoughts and suggestions. The work that you've done so
far has helped a lot.
My main concern is the same as Valentin's. The location of the documents. I
understand your point about the HTML being hit more than MD files and it's easier to
find. However, would having upstream doc on the site be confusing to a new end-user?
Transferring the pages as Valentin suggests with each release would be doable, but
painful. Who knows, maybe the user would be using upstream code anyway and would need the
latest/greatest docs. A bit of a six of one, half dozen of another situation.
With all that said, I'll favor your experience and judgment on decisions like this.
The main goal for the site was to give a place for developers and contributors an easy
place to blog to and to be able to get the information out to the end user. Any
improvements you can make in getting that info out to the end user works for me as long as
the contribution piece still remains easy to accomplish.