new navigation sidebar is effectively modal, keyboard-hostile, and hides the documentation from view

[foresto]

The not-yet-released python 3.10 and 3.11 docs theme introduces navigation sidebar behavior that is several steps backwards in usability. From what I can tell, it exhibits all these problems:

• When open, it covers up the documentation instead of letting the text reflow, making it impossible to follow my usual workflow of quickly jumping from one section to the next while reading the bits I need. The experience is like trying to navigate around modal dialog boxes in a 1990s Windows application.
• It is now inaccessible on systems without a mouse.
• Even on computers that have a mouse, viewing it is now a hassle. One must locate the mysterious hamburger button, move a hand to the mouse, aim it at the button, and click it, before the menu will appear at all. Only then can one go about looking for a needed navigation link. That's a lot of extra steps compared to simply having the links always available at the top, bottom, or side of the page.
• Scrolling through the navigation links no longer works without a mouse. Page Up/Down, arrow keys, and space bar all fail to scroll the content being read. Only mouse navigation seems to be supported.

This new design seems to have been implemented hastily, without consideration for users outside a very narrow range of workflows and devices. Please revert it, at least until something more sensible can be developed.

[JulienPalard]

Hi @foresto, I'm one of the reviewers of the PR introducing the 3.10/3.11 changes, thanks for taking the time to write some feedback.

Would you please tell us what browser (and which version) do you use? I cannot reproduce any of the mentionned issues.

[foresto]

Firefox 90 on linux.

[Mariatta]

Even on computers that have a mouse, viewing it is now a hassle. One must locate the mysterious hamburger button,

I believe the intention is that the hamburger icon should appear on smaller screen/mobile devices. Are all the issue you mentioned above only present in the mobile version, not the desktop version? Just so we understand the problem.

[foresto]

I'm not using a mobile browser, so I believe the answer is no.

Is it possible that the new theme renders a mobile experience to everyone who doesn't keep their browser window maximized or doesn't have a wide display? That would be an unfortunate mistake.

[Mariatta]

I have a larger monitor so I'm not seeing the mobile version when viewing the 3.10 docs. Perhaps it's possible to tweak the CSS. Would you mind sharing us your screen resolution?

[foresto]

My browser resolution varies from task to task, and is seldom linked to my screen resolution. I don't maximize my browser window. I often keep multiple windows side-by-side (e.g. docs, editor, and application output).

I also sometimes need the docs while on a (smaller) laptop, or when troubleshooting live code on servers with somewhat low-res screens and no mouse.

If this new theme is assuming a mobile browser based on window resolution, it's going to be wrong a lot. People read the python docs in a variety of environments, on a variety of hardware, sometimes with multitasking workflows and multiple windows. Many medium-res browsers are not phones and do not have touchscreens, but have plenty of room to display the content (if a theme hasn't hidden it).

[zware]

Patches to improve the situation for you while not reverting the usability improvements on mobile devices are more than welcome :)

In the meantime, I'll note that the links console-based browser renders docs.python.org/dev just fine regardless of window size, which may be of interest to you.

[Mariatta]

Would it be possible for us to provide a kind of "switch" so people can choose the desktop or mobile version, instead of having it detected automatically? Would that be helpful?

[foresto]

Patches to improve the situation for you while not reverting the usability improvements on mobile devices are more than welcome :)

The purpose of this bug report is not to mold the python docs to best suit me, but to point out a regression in a change that has not yet been released. Your so-called "usability improvements" break things that work today. This is your chance to fix or postpone them before impacting the general public.

Just the same, I would be disappointed to see non-mobile python programmers treated as second class citizens. I'll give it some thought if I get some free time.

In the meantime, I'll note that the links console-based browser renders docs.python.org/dev just fine regardless of window size

No, it does not. It mangles and/or discards the styling, formatting, and font rendering that make technical documentation easy to read.

[encukou]

I get the "moblie" view with a maximized window on a portrait QHD monitor with a browser sidebar. The content is about 1000px wide.

Would it be possible for us to provide a kind of "switch" so people can choose the desktop or mobile version, instead of having it detected automatically?

The old theme has a switch for the sidebar, and I do find it helpful.

[JulienPalard]

Just the same, I would be disappointed to see non-mobile python programmers treated as second class citizens.

That's not the case. The idea is not to provide a « mobile-first » experience, but a « responsive » experience, meaning: If you want to disaplay the doc in a very small window (think around the width of the actual menu) it should adapt to be easier to view.

I'm reading your initial report again, now that I understand the context:

When open, it covers up the documentation instead of letting the text reflow

Yes, there's often no point to reflow the text in a tiny-tiny-column of text, it won't be readable anyway, so maybe the switch to "cover up" should happen where it's more obvious that reflow is not wanted, like when the remaining text area is smaller than the menu width?

I'm not trying to fit the threshold so it « best suit you », I bet we'll have to doddle with it a bit before finding the sweet spot, and I also feel it could be decreased a bit. On my machine (1920 px width) it switch very soon, when it covers around 85% of my screen it already switches. What do you think @obulat?

Page Up/Down, arrow keys, and space bar all fail to scroll the content being read. Only mouse navigation seems to be supported.

Can you please try again? I tested it again, on Firefox 88, on Debian, with a brower at the right size so the menu hides, and up-down, page-up page-down and space still work for me.

[obulat]

Currently, the standard way of detecting a mobile device in CSS is using media-queries that show the screen width (not the device width). The new sidebar is shown when the screen width is less than 1023px. So, if you open the docs theme on a desktop device, and then narrow your window to less than 1023px, you will see the new menubar with the hamburger icon instead of the currently used topbar.
The value of 1023px is, indeed, wider than the usual mobile devices. The reason for choosing this width was to prevent the overflow of the top bar on screens narrower than around 1100px:

We could lower the point when the new sidebar appears to 768px (this value is used for detecting narrow devices in widely-used Bootstrap framework). This will show somewhat confusing overflow of the top bar, just like in the current version:

Can you please try again? I tested it again, on Firefox 88, on Debian, with a browser at the right size so the menu hides, and up-down, page-up page-down and space still work for me.

When you narrow down the screen on a desktop computer so that the new sidebar appears, the keyboard up-down, page-up and page-down and space work when the sidebar is closed. However, when it is open, the navigation only works within the sidebar, and you cannot close it using the keyboard.

Here is a list of possible keyboard navigation improvements for the new menu sidebar:

1. It should be impossible to tab into the sidebar when it's closed.
2. It should be possible to close the sidebar using Esc

[JulienPalard]

This will show somewhat confusing overflow of the top bar, just like in the current version

Does it mean the top bar should be enhanced to avoid this? Maybe by hiding the breadcrub between the 1023px point and the 768 one?

[obulat]

This will show somewhat confusing overflow of the top bar, just like in the current version

Does it mean the top bar should be enhanced to avoid this? Maybe by hiding the breadcrumb between the 1023px point and the 768 one?

I am afraid that hiding it between 1023px and 768px would break some user's expectations for having breadcrumbs, even if overflowing. Ideally, we would rewrite the way breadcrumbs are displayed (it is complicated by older CSS using floats, and hard-coded template). It makes sense to work on that if we are not moving to the new theme anytime soon. I would, frankly prefer the new theme.

[foresto]

When open, it covers up the documentation instead of letting the text reflow

Yes, there's often no point to reflow the text in a tiny-tiny-column of text, it won't be readable anyway, so maybe the switch to "cover up" should happen where it's more obvious that reflow is not wanted,

Obvious to whom? Even at the narrowest window width that my browsers allow (around 440 pixels on Firefox and a little wider on Chromium), there is room for the nav sidebar and readable page text alongside it. This is with default font settings on both browsers. In other words, there is no width at which reflow is unwanted. Covering up the page content defeats a core virtue of html: text reflow. It arbitrarily denies users access to that very useful feature while adding no functional benefit that I can see. Why not just let the browser do its job?

Page Up/Down, arrow keys, and space bar all fail to scroll the content being read. Only mouse navigation seems to be supported.

Can you please try again?

Sure. I just tried the stdtypes page with a browser view area 800 pixels wide. When it loads, the page up/down and cursor keys correctly scroll the page. If I then click the hamburger button, the sidebar appears, and the page up/down and cursor keys no longer have any effect on anything. Both the sidebar and the partially-hidden page beneath it now ignore those keystrokes, despite both of them having enough content to allow scrolling. Firefox 90.0, Xfce 4.14.

Currently, the standard way of detecting a mobile device in CSS is using media-queries that show the screen width

What standard is that? Where can I read it, please?

I suspect that this is not a standard, but merely a heuristic that emerged at a time when touchscreen browsers were almost universally lower resolution than desktops. Using CSS media queries made a lot of sense at that time, since they are performant and avoid dependence on javascript. Sadly, the foundation assumption of that practice is no longer true: touchscreen browsers are often rather high resolution these days, and many keyboard/mouse users (especially in the programming community) tile our windows to lower resolution so we can multitask.

So, today, that practice is fundamentally broken.

Is there a media query that detects a touchscreen device? Better still, can we design documentation pages such that they don't need application-like behavior with modes and pop-up menus?

The new sidebar is shown when the screen width is less than 1023px. [...] The reason for choosing this width was to prevent the overflow of the top bar on screens narrower than around 1100px

Ideally, we would rewrite the way breadcrumbs are displayed (it is complicated by older CSS using floats, and hard-coded template).

Ah, I see. That makes sense. Baggage from past designs can make conservative changes challenging.

Okay, here are my suggestions:

• Rather than covering the page content with an overlapping sidebar, let the page text reflow around the sidebar, and make it collapsible, as it is today. This avoids robbing people of the ability to read index and page content side-by-side if they want to. It might make the wrapped page text look a little funny to people with narrow screens and large fonts, but those people are already focused on the sidebar when they open it, so they lose nothing with this approach.
• Rather than putting the nav links in hamburger menu mode when the view is narrow, consider putting them at the top of the page, like a traditional table of contents. Navigating from there to the main content is as easy as tapping one of the links, and jumping back again is as easy as flicking the screen or pressing the home key. This top-of-page nav area could still be collapsible to accommodate folks who don't need it (just as the sidebar is in the stable docs today).
• When space is scarce, shrink the page margins. They waste space that could be used for perfectly readable text.
• Rather than imposing a minimum width to accommodate all the widgets side-by-side in the top bar, let it wrap. Its purpose won't be confusing if the containing box is allowed to expand around it.
• To avoid widow/orphan breadcrumbs in a wrapped top bar, either place them in a div or move them to the rightmost end of the bar. This way, breadcrumbs wrapping to a new line will read just like any other text, and not be confusing. Alternatively, move the breadcrumbs out of the top bar, to the top of the nav area instead.
• If layout switching absolutely must be done based on window width, set the threshold in ex units instead of px units, so the switch will have some relation to how much text can fit on a line, regardless of platform and font configuration.

[JulienPalard]

I would, frankly prefer the new theme.

You mean furo?