So, I waited a couple days to see if anyone else commented first, but now I’m going to share my thoughts.
I agree that we need to find a way to make more room for wide tables and examples. I am not particularly happy with certain details of the current implementation, however.
We now have body text that is restricted in width quite a bit, while other content is not, resulting in an enormous disparity in how wide things are. For example:
See how the text width varies wildly between the body text and the note and summary boxes? This is, I think, an unfortunate situation where the result is just weird to look at. Now, I know I tend to be a little sensitive about layout issues (the varying line lengths really distract me) and I personally have always preferred to have control over line length by changing my window size, instead of having a fixed line length, but even leaving those issues aside, there are definitely some design quirks here that we need to sort out.
Basically, right now, it looks like something is wrong with the layout of the body text, as if someone accidentally slapped a width on it that doesn’t match everything else on the site.
I see a few options, and I’m sure there are others that I’ve missed:
- Make boxes like note, summary, syntax, etc. default to the same width as the text, only getting wider if the content demands it. I would think this would more or less mean adding a
min-width
to them, or something like that.
- For parts of a document that don’t need to use the space to the right, why not make the body two columns of text, using the full width of the available space? That would give you more text visible at once while keeping the line lengths low. I expect this could be tricky to do, but if it could be done it might be an amazing solution.
- Make the body text flow the full width of the available space, allowing the user’s window size to control line length. This is my personal favorite option but I know it defies all the rules about “long lines are bad”.

- Add some sort of a background to the body area (or to the empty area next to it) to help make it look less like a formatting snafu to have the body text not using the space that seems to belong to it.
As to #1, I’ve been told this option doesn’t really make sense because “these are things that are supposed to stand out anyway,” but I think the backgrounds and borders and such do that nicely, and having things stand out by looking like a layout mistake is not the best way to go. 
#2 appeals to me quite a bit as a second favorite and might even edge out #3 to become my favorite. Not necessarily easy to implement but it should be feasible, and it would make great use of space, while also adding character to the site by presenting the content in varying layouts between two-column and one-column depending on whether or not there’s a table or example nearby.
As for #3, which I know I’m biased toward but am not trying to push at anyone, I know this violates current principles about wide lines of text being hard on the eyes or something like that, but I feel that if someone is able to control the line length, they can choose a width they’re comfortable with. That seems to make more sense than anything else. I personally have always found long lines both perfectly comfortable to read and more convenient because I can get more content on the screen at a time. That saves me from scrolling as much while using a page as reference while working, for example.
As for #4… this is a terrible idea but it would at least help make it more clear that this is intentional. Even after looking at it for a couple of days, it still looks like a rendering error to me – like something failed to load or something.
Sheppy