When I discovered Stack Overflow, I remember that the interface was immediately intuitive to me. Title goes here, question goes there, add tags, done. Add a comment, cool. Share the link, easy. Vote to close, done.
This is not my experience with Documentation. Whenever I follow someone's link to a Documentation Example, I get super confused.
The table of contents and the content being almost the same width in the split screen view is confusing
(This is not as egregious in the single-column view - but most of the other problems remain.)
It is awfully easy to accidentally scroll away from the section I wanted to read/jump to (because there is content above and below, just touching the scroll wheel makes you lose it)
I still need 30 secs each time to figure out what I need to do e.g. when I want to suggest a new edit to something
I still need to hover over each icon each time to figure out what they mean
Having the examples be part of a list that you can scroll up and down (and jump to dynamically) doesn't seem to serve any purpose currently, as the order of examples is random.
This doesn't feel like an ideal experience, neither as a consumer (imagine someone ending up directly at an example through Google), nor as an editor/reviewer. It also doesn't feel like a part of SO.
Could this whole thing not be made much more to resemble the traditional Q&A interface - splitting each example into an artifact of its own?
To oversimplify:
I realize the Documentation team must have spent a lot of time on how to approach Documentation's UI... there are probably good reasons why everything looks like it does that I just don't see.
But I really have problems using the UI as it is, and the fancy JS feels counterproductive to the experience.