Content bug: Sidebar "Related Topics" no longer shows any specific related topics on CSS pages

[AlpyneDreams]

What is the problem?

Many CSS pages used to have specific related topics in the sidebar listed under "Related Topics". Generally topics from a certain category (like "Fonts", " Box Model", etc) would get all the related pages from that category.

Now it simply displays the entire table of contents for the whole section of MDN: it lists every single CSS topic, every property, etc., even though the heading still says "Related Topics". Many of the links that were previously listed under Related Topics are now hard to find in these giant alphabetical lists, if they're even present.

Example: (click to open images)

• Left: (Expected) Archived version from March 24: font-family (Archived)
• Right: (Problem) Current version: font-family (as of April 4)
  

Notice how previously the "Related Topics" were actually related to the specific topic, and now every single topic is listed instead.

What did you expect to see?

I personally found the related links to be very useful in using MDN, and I think they should still be included, even if this was intentional (I have no idea if it was), surely it would be better to still include the specific related topics above the rest of the table of contents?

Alternatively, these links could go under "See also", but there might be some redundancy with what's already there, and there are typically fewer links under "See also" than under "Related Topics"

I believe the change may have something to do with PR #3165 (fixing issue #3025), but I can't find the exact change made for the examples I'm providing as it is a very large PR.

Other possibly relevant issues:

• Lots of hardcoded sidebars #2454 - "Lots of hardcoded sidebars"
• Empty „see also” section #181 - "Empty 'see also' section"

What page(s) did you find the problem on?

• Lots of CSS pages
  • font-family (vs. Archived 3/24)
    • Previously linked to "CSS Fonts" and many related topics
  • width (vs. Archived 3/8)
    • Previously linked to "CSS Box Model" and many related topics
  • Many more

Specific page section or heading?

In the sidebar or subnav, under "Related Topics" (class is sidebar-quicklinks). I've only noticed it on CSS pages however it may affect other sections too.

Did you test this? If so, how?

N/A

---

Edit 1: Minor formatting tweaks.

Edit 2: Add note about "See also"

[sideshowbarker]

@mdn/core-dev

[escattone]

@AlpyneDreams See mdn/yari#3228 (cc @wbamberg)

[AlpyneDreams]

@AlpyneDreams See mdn/yari#3228 (cc @wbamberg)

Ah, thanks. Will this issue have to move to yari or can it stay here?

I maintain that this is still a problem, especially given the performance issues in mdn/yari#3332.

[escattone]

@AlpyneDreams It can stay here (at least for now).

[wbamberg]

I'm sorry you find the new sidebar less useful. Since I'm responsible for the changes perhaps I should try to explain some of my reasoning.

This is largely going to be a rehash of https://discourse.mozilla.org/t/css-sidebar-proposal/49500, but I'll mostly stick to the usability issues and not the internal complexity).

I agree that there are some places where the old sidebar did give you a useful set of related properties, and font is a good example of this. And I agree that it's a regression not to be able to make these obvious and easily reachable. However, there were many cases where it didn't.

The old CSS sidebar gave you links to the items that belonged in the same CSS module. If the module to which an item belongs does not map cleanly to a group of related items, which is often the case, then the sidebar wasn't useful, and there are many cases like this. For example:

• Flexbox is a module, so you get a list of related flex properties on these pages. However, the properties used to control alignment in Flexbox, like align-items, are in a separate module (because they are used by more than just Flexbox). So even though it's extremely likely that someone looking at flex will care about align-items, it's not in the sidebar.

• When the property lives in a very small module, like filter, the sidebar gives you almost nothing at all. Although the introductory paragraph for filter actually says "Filters are commonly used to adjust the rendering of images, backgrounds, and borders" you don't get any links to any of those related properties, because they're in a different module.

• The mechanism for determining the module a property belongs to is complex and easy for people to get wrong, and then the sidebars are not at all useful: pointer-events, overflow-anchor.

But aside from that, and whether or not your current module was actually a useful set of properties, the old sidebar was brittle: if you needed to navigate from the properties in your current module to another property (e.g. font to color) it didn't help at all. In fact the CSS docs didn't provide any consistent and reasonably simple way to perform a navigation like this.

So those are the main problems that the new sidebar tries to address.

---

I do agree it's a shame that in many cases the old sidebar gave easy access to some closely related properties, and now this is a bit harder. I think this is a tradeoff to address the other problems outlined above. We could perhaps keep the old "related-items-in-this-module" bit in the sidebar, and have the "everything" sidebar under it:

- Flex properties
    - flex-basis
    - flex-direction
    - ...
- Learn
   - CSS first steps
   - ...
- Reference
   - Properties
       - // all properties a-z

There are a couple of things I don't like about this.

First it keeps all the complexity and fragility of the old sidebar, and adds some more.

Second, which I care about more: I really like it when sidebars stay the same when you navigate. I think this helps people learn how to find things, and generally makes things behave in a more predictable way. But maybe I'm wrong about this!

An alternative which I think would help would be for the sidebar to expand the section that contains the current page, and scroll to make the current item visible. So for example if you were on font you would see:

---

---

This means, at least, that if you were at font you would have easy access to all the font* properties. Unfortunately that depends on having a scrollable sidebar, which we don't have at the moment.

Or maybe I'm just wrong, and we should revert the change 🤷.

[hamishwillee]

@wbamberg IMO FWIW

• sidebars in MDN suck and what you have done is a vast improvement.
• I also like a consistent sidebar as you navigate. The whole point of a sidebar is to provide a guided context, and that doesn't work if the map changes every time you move.
• I would very much like a sidebar that supported expanding/opening/scrolling to the current context - and if we could encourage something like that to be developed it would be a good thing.

You suggested "We could perhaps keep the old "related-items-in-this-module" bit in the sidebar, and have the "everything" sidebar under it".
As long as the existence of this is the exception and not the rule (and the list is kept short), then I think this a pragmatic way of overcoming limitations of the current infrastructure, in the cases where it most matters.

[AlpyneDreams]

@wbamberg:

Second, which I care about more: I really like it when sidebars stay the same when you navigate. I think this helps people learn how to find things, and generally makes things behave in a more predictable way. But maybe I'm wrong about this!

I do very much agree with this principle but I think that the number of properties in CSS means that getting a strong mental model of a single sidebar is a lot harder, so I'm not sure the consistency is as beneficial as it would be were there significantly less stuff to index.

I think you could get away with sticking a Related Topics section on top of the full sidebar as you suggest without breaking consistency as much by either by making it collapsible, or putting some sort of line between the two sections, something like that. (I agree with @hamishwillee's perspective about this idea too)

Alternatively, I think this might be a good excuse to expand the function of the "See Also" section, which is often not very detailed.

• I think it would be a good place to put Related Topics, perhaps underneath the current article-specific links.
• Wikipedia provides a really good example in their category tables at the bottom of articles (pictured below), and I suspect something similar could be done with the existing Related Topics link structure without having to change their structure much.

[AlpyneDreams]

Also,

• When the property lives in a very small module, like filter, the sidebar gives you almost nothing at all. Although the introductory paragraph for filter actually says "Filters are commonly used to adjust the rendering of images, backgrounds, and borders" you don't get any links to any of those related properties, because they're in a different module.

While this was definitely an issue, I'd argue that the problem with filter specifically was there were like 10 whole filter effect functions (blur(), sepia(), etc.), each with their own page, all of which were completely missing from that sidebar and instead roped in with the less intuitively named <filter-function> page.

[teoli2003]

Given that the sidebar now displays:

I think the original problem in this issue is solved. We continue to work to improve sidebars (and see also sections), but that's not directly actionable here.

So I'm closing this issue as completed. If I'm mistaken, please feel free to reopen it with some explanation about what is left to do.