Waste less vertical space at top of rendered PEP

[gvanrossum]

This is about usability of peps rendered on peps.python.org.

At the top of a PEP (e.g. https://peps.python.org/pep-0687/) there's a table with metadata. Most of that I ignore or is even duplicate (the title). I usually have to scroll right past that to the Abstract. Maybe the metadata could be collapsed, like the ToC? Or moved to the sidebar, like the ToC?

[CAM-Gerlach]

Hmm, yeah, not sure why the title and the PEP number is actually displayed in the table, since it is in large type right above it, though most the rest can be rather useful. There's also some margins that can be tightened up and a chunk of extra vertical space between the headers and the contents that can be mostly elided. All told, just those changes cut the total vertical space occupied by the header table and its margins by around half. Here's how that would look:

Also, note that #2467 helps a little as well by displaying list/venue names in more cases rather than long, noisy raw links in the header fields.

If we want to go further, we could make the table collapsible by embedding it in a details block, opened by default.

[JelleZijlstra]

What if we displayed the table below the abstract?

[Rosuav]

Cool! Would there be a way to hide email addresses behind something so they're not taking up all the space? The obvious way is a link, but that would encourage people to email PEP authors with all manner of questions, so I think that would probably be a bad idea, but maybe something like <abbr title="example@example.org">Example Person</abbr> ? Not sure whether there's any a11y issues from hiding those addresses.

[gvanrossum]

Do we really need those horizontal lines between the table items? Without those I could be satisfied.

[CAM-Gerlach]

What if we displayed the table below the abstract?

I thought about that, but that would be substantially more complicated to do from a technical perspective, and also invites a lot of edge cases, e.g. some PEPs have acceptance, rejection, withdrawal, etc. above the abstract and some below, and some have them as sections and some as admonitions, some PEPs have other elements before the abstract and some have no abstract at all

Would there be a way to hide email addresses behind something so they're not taking up all the space?

We can't have them be mailto links as that would defeat the obfuscation we promise authors. We could make them abbr nodes with a bit more fiddling in the header transform, but I'm not sure if they need to be in the rendered PEPs at all, since in general we don't want to encourage people to nag PEP authors directly at their personal emails as opposed to using the Discussions-To thread or other means of communication, and if they (or us) really do need to get it touch, they can still be found in the linked source.

FYI, #2484 makes either of these options possible to do since it conforms and validates the format, making it easy and reliable to process mechanically.

Do we really need those horizontal lines between the table items? Without those I could be satisfied.

I personally prefer the lines as it helps my eyes to track which field corresponds to which value, especially with less vertical space between them, but aligning the header keys to the right does at least partially mitigate this. Putting that all together, combined with the email changes suggested above, it looks like this:

Screenshot

I do think it looks a little odd without some sort of visual separation of the block, like a border box around the whole thing, but that in turn looks somewhat odd too with the much shorter max value column widths between the authors and Discussions-To/Resolutions changes in #2467

Screenshot

[Rosuav]

We could make them abbr nodes with a bit more fiddling in the header transform, but I'm not sure if they need to be in the rendered PEPs at all ... they can still be found in the linked source.

If that's sufficient, then I say go for it! One extra step of "go to the source" doesn't seem too much hassle for the rare cases where it's actually needed.

[gvanrossum]

Honestly I still think you’re overestimating how much value the metadata has for most readers who aren’t PEP editors. I also just checked my phone and there the table takes up the entire first screen. So I still want less space taken up by the table, and collapsing sounds like a mighty fine compromise…

[CAM-Gerlach]

I'm not sure about it; most of the remaining fields are fairly important for readers—properly attributing the PEP to its authors, clearly communicating whether it is accepted or just a proposed draft, and merely a whitepaper or a recognized standard, providing a place to provide feedback, making clear what Python version it will apply to, etc. I don't think we should hide that behind a dropdown that users have to find and click, at least by default.

And I don't think we have to. With only the changes already proposed here, before any further responsive optimization, the height of the table is reduced to close to a third of what it is currently. See, e.g., this comparison on a Pixel 3a (my phone), which has a relatively small screen:

Screenshot

[gvanrossum]

You drive a hard bargain. I just hope I don’t have to review the cod implementing it. :)

[CAM-Gerlach]

Its called...CAMpromise (ba dum tush)

Don't worry, we have @hugovk for that :), and besides the CSS tweaks it should be just a couple changes to the header transforms. For the authors, I'll wait until #2484 is merged, though to avoid running into the various edge cases that fixes/prevents.

Now if only reducing the vertical space my own writing takes up was that easy...though I'm working on that.

[AA-Turner]

Another approach would be to e.g. inline the author metadata as a by-line, and have the required fields in the sidebar with the "full" metadata as a collapsed block. There's also potential to somewhat specialise and display the Python-Version for standards-track PEPs, etc.

I have a view in my head of what it would be like, but not the time to implement it now, so @CAM-Gerlach's suggestions seem a reasonable first stab. (This comment is sort of a self-imposed commitment device)

A

[hugovk]

🙋 Happy to review! :)

The CAMpromise looks good. As it's quite compact now, we can probably skip the horizontal lines. Anyway, we can look again when we have a build preview of the PR, and I'll check #2484 later today.

[CAM-Gerlach]

I've finished the various changes and opened them as PR #2533 . In the final version, I've made a few tweaks to the margins and line height further decrease the vertical space consumption and better align things, especially on mobile:

Desktop (Before/After)

Mobile (Before/Previous/Latest)

Another approach would be to e.g. inline the author metadata as a by-line, and have the required fields in the sidebar with the "full" metadata as a collapsed block. There's also potential to somewhat specialise and display the Python-Version for standards-track PEPs, etc.

That seems rather overly complicated for the benefit it would provide, and I don't think its a good fit for the sidebar as it doesn't need to be accessible all the time and it is much too narrow (especially with the changes to allow the sidebar to be used at narrower widths) and would require an alternative solution anyway on smaller devices, which is where the length of the headers has the most impact. But the proof is in the pudding, err the mockup/preview, and in any case I'm getting off topic here.