Consider "fly-out" menu on (some?) docs pages?

[bugfolder]

Several of the docs pages (e.g., Form API, Functions contain wide tables that are (or would be) overlapped by the right-side menu (see https://github.com/backdrop-ops/docs.backdropcms.org/issues/152). To fix those, we gave those pages a different layout that moves the menu to the bottom of the page (only recently, for Functions; it's been that way for a while for Form API). So now, for example, while Functions page used to look like this:

it now looks like this:

However, with the menu block now at the bottom, it's much less usable, since one needs to scroll a long way to get to it. Here's a full-page screen shot, with the menu outlined in red:

I'd like to suggest—or solicit suggestions for—alternative things we could do that would be more usable. One possibility would be a fly-out menu, such as here (which I ginned up with a little CSS on my local site):

https://user-images.githubusercontent.com/29214084/204025292-ade3f332-df8f-4e2f-97d4-44e2e83607cb.mov

What do people think of this? It's layout-specific, so if you'd like to try it out, I could put this on one or two pages of the docs site. Or other ideas? (Maybe change the theme so that it can accommodate arbitrary-width content region?) I don't claim that flyout-menu is the best solution, but it seems like there's a lot of things that would be better than just shoving the menu block all the way to the bottom of the page.

[yorkshire-pudding]

@bugfolder - this looks great and I think it would be a significant improvement. I'm not sure how important it is as I don't know how many people look at the docs site on a mobile (perhaps stats can tell us this?) but what does it do/look like on a mobile sized screen?

[bugfolder]

what does it do/look like on a mobile sized screen?

The existing layout/theme hamburgerizes the menu for screens narrower than 768px, so I left that as the behavior (with the collapsed menu at the bottom); the flyout menu only takes over for >768px. (I don't know what the behavior is for touch interfaces; I don't have a way of testing that, although I could put it on the production site and try it out—but I thought I should get some initial feedback first.)

[klonos]

The suggested fly-out menu is indeed a very good improvement over the current situation.

Unless anyone else has any other suggestion to solve this issue, I say go for it 👍🏼

[bugfolder]

Via MAMP Viewer, I was able to try this out on my iPad from my local site, and it still works with a touch interface. So I'm going to go ahead and put it on production.

[bugfolder]

Done. You can see this in action on the following pages:

• API > Topics
• API > Functions
• API > Classes
• API > Files
• API > Globals

Leaving this issue open for the moment to collect further comments. (E.g., should it be applied more broadly across the docs site?)

[yorkshire-pudding]

Thank you @bugfolder - this looks really good. I'd be open to having this on all pages

[docwilmot]

Looks nice. Would be better fixed though. And what about FormAPI page?

[bugfolder]

Would be better fixed though.

@docwilmot, I'm not sure what you mean by that. Could you elaborate?

And what about FormAPI page?

It could be added for FormAPI page, but probably needs some additional CSS to handle the extra-wide tables at the top (perhaps give their container overflow-x: scroll). At ordinary window width, the flyout menu overlaps the table, but if one expands the window to be large enough to accommodate the full width of the table, it works.

[docwilmot]

Instead of position: absolute, position: fixed. Would need extra magic for scrolling and the top margins etc. Maybe "would be better" is too strong, its my preference I should say.

And could we consider putting the menu on the left instead, for all pages? That would solve the wide tables issue

[bugfolder]

Instead of position: absolute, position: fixed

I'd initially tried that, so that the menu would stay visible as one scrolled the window content, but the problem I ran into was that on moderate-sized screens, the menu is taller than the window, and once it's fixed, there was no way to see the bottom of it.

And could we consider putting the menu on the left instead, for all pages? That would solve the wide tables issue.

That sounds good.

[bugfolder]

I've moved the flyout menu to the left on the pages listed above and added it to the Form API page.

Looking around a bit raises two new questions:

• Many of the API pages would benefit from having the full width of the page to display content (see, for example, https://docs.backdropcms.org/api/backdrop/core%21modules%21views%21includes%21handlers.inc/class/views_handler/1). Should we use the layout with the flyout menu for all API pages?

• For "regular prose" pages (all of the non-API sections of the docs site), would it help consistency to move the fixed menu block to the left column, rather than the right column (i.e., use Moscone template, rather than Moscone Flipped template)? That way, the menu block is always on the left, whether it's fixed or flyout.

[yorkshire-pudding]

I think both of those proposals make sense.

[docwilmot]

I'd initially tried that, so that the menu would stay visible as one scrolled the window content, but the problem I ran into was that on moderate-sized screens, the menu is taller than the window, and once it's fixed, there was no way to see the bottom of it.

Add a scrollbar? Or something like https://css-tricks.com/a-dynamically-sized-sticky-sidebar-with-html-and-css/? Googling (briefly) for "sticky sidebar" gives some ideas.

I also support moving the sidebar to the left for all pages.

[bugfolder]

I also support moving the sidebar to the left for all pages.

Sidebar is now on the left.

Add a scrollbar? Or something like https://css-tricks.com/a-dynamically-sized-sticky-sidebar-with-html-and-css/? Googling (briefly) for "sticky sidebar" gives some ideas.

These all seem like possibilities, but I'll suggest they be pursued via a follow-up issue.

[jenlampton]

I also support moving the sidebar to the left for all pages.

Just noting here that this seems like a mistake. The site feels less polished and much harder to use now. The navigation feels like it's "in the way" when it's on the left. I want to read the text on the page, and my eye struggles to shift over to the right in order to start reading. Additionally, these pages were previously really easy to scan by jumping your eye down the left side of the page, and that kind of easy scanning has also been interrupted since there's no easy left edge to follow.

I don't think we should make executive decisions like this without consulting a designer. The API site used to only affect those people who were consulting the developer documentation, but now that it includes the handbook, we're also inconveniencing all the people who need documentation.

[yorkshire-pudding]

I don't know how it could feel less polished before this issue, or perhaps you only mean the simpler text only pages that don't have wide content. This issue was a follow on issue to #152 which fixed it by putting the menu below the content; this was not polished! It didn't feel polished when the menu, even the right hand fly out menu overlapped the table (see https://github.com/backdrop-ops/docs.backdropcms.org/issues/215#issuecomment-1329213788).

Perhaps we need to rethink the usability of the difficult pages with large tables as I don't think we should change the menu from what it is unless it works with all content. It was a little jarring to have the menu jump from one side to the other so it did make sense to move the menu completely to the left.

Do we split the user guide from the developer documentation, whilst still keeping on the same site? Perhaps that would be a better user experience for both?

Either way, I suggest these are separate issues.

I don't think we should make executive decisions like this without consulting a designer.

It didn't feel like an executive decision; more like how do we fix bugs and usability. We don't seem to have ready access to a designer but we do have regular volunteers who think about usability who supported this.

As someone who regularly looks at these pages to find my way, I really appreciated @bugfolder 's work on making this so much more usable. I also use the menu a lot to navigate sub pages of sections so this has made my life a lot easier!

[jenlampton]

Why does it need to be a requirement that the menu be treated exactly the same way for different types of pages? Can't we just do what's best for each situation, rather than making the experience worse on most pages, for the sake of consistency?

I agree we should consider other options for problem pages, but that doesn't mean we need to change the pages that don't have issues.

I understand the desire for consistency, on this one site, but I think the user experience of each page far is more important. Plus, we've now lost consistency with all the other sites (and most people won't know the difference).

What exactly was the problem we were trying to solve by moving the menu to the left? It's not like people won't be able to find navigation on the right if it was on the left on another page.

The unpolished feel is probably because nobody planned for the menu to be on the left, so there are likely spacing issues that were never encountered before now. Yes, those should probably be fixed too, but before we spend any time on that I think the larger usability issues need to be discussed.

Maybe we should put together a collection of issues for designer review and see if we can get some advice for the collection. Designing by committee never goes well :)

On Fri, Jan 27, 2023, 2:26 AM Martin Price @.***> wrote:

I don't know how it could feel less polished before this issue, or perhaps you only mean the simpler text only pages that don't have wide content. This issue was a follow on issue to #152 https://github.com/backdrop-ops/docs.backdropcms.org/issues/152 which fixed it by putting the menu below the content; this was not polished! It didn't feel polished when the menu, even the right hand fly out menu overlapped the table (see #215 (comment) https://github.com/backdrop-ops/docs.backdropcms.org/issues/215#issuecomment-1329213788 ).

Perhaps we need to rethink the usability of the difficult pages with large tables as I don't think we should change the menu from what it is unless it works with all content. It was a little jarring to have the menu jump from one side to the other so it did make sense to move the menu completely to the left.

Do we split the user guide from the developer documentation, whilst still keeping on the same site? Perhaps that would be a better user experience for both?

Either way, I suggest these are separate issues.

I don't think we should make executive decisions like this without consulting a designer. It didn't feel like an executive decision; more like how do we fix bugs and usability. We don't seem to have ready access to a designer but we do have regular volunteers who think about usability who supported this.

As someone who regularly looks at these pages to find my way, I really appreciated @bugfolder https://github.com/bugfolder 's work on making this so much more usable. I also use the menu a lot to navigate sub pages of sections so this has made my life a lot easier!

— Reply to this email directly, view it on GitHub https://github.com/backdrop-ops/docs.backdropcms.org/issues/215#issuecomment-1406305986, or unsubscribe https://github.com/notifications/unsubscribe-auth/AADBER7DZ3YYOEUZ3BAZ6GDWUOPDZANCNFSM6AAAAAASLPPLRY . You are receiving this because you commented.Message ID: @.***>

[irinaz]

Is this problem related to layout that @stpaultim had in another issue? I am using harris-flexible layout where bootstrap for classes are configured differently and with that layout sidebar will be automatically pushed down without additional css by bootstrap setup.

[bugfolder]

Is this problem related to layout that @stpaultim had in another issue?

Hard to say; it's not clear which issue you're referring to.

I think, though, that this is a fairly accurate summary of the problem(s) addressed in this issue:

• On many pages of tabular information in the API, the content is quite wide, and the right sidebar was covering up essential content, making it impossible to use those pages.
• On other pages of tabular content, the content was getting squished so that the table was much longer than optimal and the individual columns were much taller than optimal.

The suggested solution was to use a fly-out menu on the right on those pages. There were two positive comments from long-time users, no negative comments. Then a suggestion to move the FOM to the left, so it wouldn't cover up super-wide pages, like the Form API.

That, however, resulted in the menu switching from side to side depending on what page you were on. It was then suggested to move the sidebar to the left for all pages. Two commenters liked it (three, if you count me), no one opposed. After a few weeks with no further comments, including none opposed, I implemented the change. It was (presumably) considered an improvement by all the people who had been participating in the issue up to that point (at least, none of them objected after the change.)

A few weeks later, @jenlampton noted that her experience was that for much of the site having the menu on the left was a degradation (which I would not try to dispute, since we each have our own experiences) and suggested that the process followed to get to the change (soliciting comments, getting consensus among multiple commenters, waiting multiple weeks for feedback, then proceeding with the consensus change) was an "executive decision" (which I would kinda dispute, since that seemed to be the process followed in lots of other issues).

Certainly no action is final, and we could improve the UI for the docs site further. At least now, the unusable pages are usable, so we could continue to use them while we discuss and find a still better solution. (Since this issue is closed, perhaps a follow-up issue would be best? Or we could reopen this issue, as folks prefer.)

Since Jen asked a few questions above, let me address some of them.

Why does it need to be a requirement that the menu be treated exactly the same way for different types of pages?

It doesn't need to be a requirement. In fact, the implemented solution uses the fly-out menu for some pages (those that benefit from full-width content) and a sidebar menu for others. Having the menu switch between FOM and SBM from page to page didn't seem too jarring, but having it switch from side to side definitely did. Perhaps, though, large sections could switch from side to side: for example, putting it back on the right for most of the docs site, but on the left for all of the API pages.

What exactly was the problem we were trying to solve by moving the menu to the left?

I hope that was adequately addressed by the summary above.

Maybe we should put together a collection of issues for designer review

That sounds good. Perhaps a designer could join this issue discussion?

and see if we can get some advice for the collection. Designing by committee never goes well :)

On the other hand, getting input from multiple people seems to be a common practice around here, and acting based on a consensus of comments often goes well. An awful lot of issues in B-land have some element of design to them. So maybe rather than trying to distinguish between committee and consensus, we could just proceed with suggestions for further or alternative improvements, and/or someone who knows a designer could get them to jump in and share their expertise?

[jenlampton]

Then a suggestion to move the FOM to the left, so it wouldn't cover up super-wide pages, like the Form API.

Moving the sidebar from the right to the left does not stop the sidebar from covering the content. It doesn't change the width of the page: 4 + 8 is the same as 8 + 4.

Something else had to be done to solve the width issue... and couldn't that something work for both left and right menus?

That, however, resulted in the menu switching from side to side depending on what page you were on.

This is also not a problem?

and suggested that the process followed to get to the change was an "executive decision"

I'm sorry about that wording :(

I wasn't aware of the process, or even any suggestions to alter the design. I had obviously missed the suggestion to move the menu to the left hand side until after it was implemented.

At least now, the unusable pages are usable

The unusable pages were made usable when the menu was moved below the content (and maybe also by adding a fly-out menu?). Moving the sidebar came later.

What exactly was the problem we were trying to solve by moving the menu to the left?

I hope that was adequately addressed by the summary above.

Sorry, but I'm still lost as to why it was moved to the left. Didn't the fly-out menu solve the problems mentioned above?

Perhaps, though, large sections could switch from side to side: for example, putting it back on the right for most of the docs site, but on the left for all of the API pages.

I would argue that it's more important that that people be able to scan the API pages. The documentation pages contain larger paragraphs of text, with fewer headings, and create more of their own "left edge" that the eye can follow. Plus, people probably are reading the whole page (or at least paragraph), as opposed to the API docs where people are rarely read the whole page, and are usually only scanning for the definition of a single argument (for example).

The menu was designed to be on the right. Moving it to the left will require that we also refactor it to work as a left side navigation. It's too wide for a left hand menu, for starters, and making it narrower would require shortening the menu links, or decreasing the font size, which might also require a font-weight change, or even a font-change. Or, if we decide that we're going to live with the excessively wide menu, then we need to make other design changes to make the pages still be easy to use.

On the other hand, getting input from multiple people seems to be a common practice around here, and acting based on a consensus of comments often goes well.

My point wasn't that the conversation doesn't go well, or that consensus is a bad idea, it was that a design that comes out of this process is much worse, and designing by consensus is not something that's common practice around here. The end result of design by committee ends up feeling sloppy and unpolished. (Honestly, it's why most open source software ends up with such poor design.)

This problem (pooor design by committee) is something Backdrop has been aware of since the very beginning, and because Design is so important for first impressions, it's also why we spent our meager starting budget on design resources.

Since this issue is closed, perhaps a follow-up issue would be best? Or we could reopen this issue, as folks prefer.

I'd be happier with a follow-up issue, but I'd like to determine whether that issue should be "Make the site/menu work with a left sidebar" or "Move the menu back to the right and also do something else to solve some other problem". But I'm still missing the problem :)

We've discussed doing a brand refresh for Backdrop and the b.org themes, perhaps that should include how to handle both left and right sidebars for each site. Maybe that's what the follow-up issue should be?

[bugfolder]

I miswrote on the rationale for moving the sidebar to the left; it was to have the flyout and menu on the same side (and the flyout worked best on the left.) They don't have to be on the same side, of course. Visually, it was more jarring to me (and at least some others) to have the flyout on the left for some pages but the sidebar menu on the right for others than to have the sidebar on the left always, but I acknowledge that others find the left sidebar menu jarring. (Having the sidebar menu pushed below the content on widescreen devices, though, was also pretty jarring and not very useful.)

At any rate, I'm happy to turn the problem over to the designer, and/or to live with flyout-on-left, sidebar-menu-on-right, or other variations—as long as I can see API pages not covered up and tables not unduly squashed.

[irinaz]

@jenlampton , what is best way to select and reach out to designer?

[jenlampton]

I miswrote on the rationale for moving the sidebar to the left; it was to have the flyout and menu on the same side (and the flyout worked best on the left.) They don't have to be on the same side, of course. Visually, it was more jarring to me (and at least some others) to have the flyout on the left for some pages but the sidebar menu on the right for others ...

Ah, that makes more sense :) Thanks for taking the time to explain it to me.

@irinaz I would start by @-mentioning our previous designers in the issue (once it's created) to see if they are interested in helping us out again, but we also have some newer members of the community who have also voiced an interest in working on a brand update, and it would be great to involve them too.