Improve Navigation Menu Readability with Shortened Labels & Tooltips

[chiztechnology]

Description

Reduced overly long navigation menu labels in the Docusaurus sidebar to improve readability, layout stability, and overall user experience.

Related Issue

Related to #155

Key Changes

• Shortened selected _category_.yml labels:
  • Developer Experience Working Group → Dev Experience WG
  • Maintainer Retainer Program (MRP) → Maintainer Program
  • How To Guide → How-To
• Added CSS truncation to prevent layout breaking:
  • text-overflow: ellipsis
  • white-space: nowrap
  • overflow: hidden
• Implemented tooltip system in src/theme/Root.tsx:
  • Maps shortened labels to full titles
  • Dynamically injects title attributes
  • Uses MutationObserver to support dynamically rendered menu items
• Ensured compatibility with light/dark themes and responsive layouts

This preserves full context via hover tooltips while significantly improving sidebar compactness and visual clarity.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Testing

• I have tested these changes locally
• I have checked for broken links
• Code examples have been tested

Checklist

• My code follows the style guidelines
• I have performed a self-review
• I have made corresponding changes to documentation
• My changes generate no new warnings

[Ranchhand87]

This is a program under the Paid Open Source Model (POSM), The OSC might need to weigh in when it comes to reducing the Title.

If there were multiple maintainer programs, that would make sense to reduce, otherwise while the focus is retained on MRP, I am not sure that this should change, Maybe the page needs to move?

[chiztechnology]

That makes sense.

My goal with the change was purely to improve sidebar readability and layout consistency, especially on smaller screens. There was no intention to reduce the formal identity or visibility of the Maintainer Retainer Program (MRP).

Given that this falls under POSM governance and may carry formal significance, I completely understand that shortening the title could introduce ambiguity.

I Can:

• Revert the Maintainer Retainer Program (MRP) title change,
• Keep the full official name in the sidebar,
• Or explore alternative UX approaches (e.g., restructuring navigation, moving the page, or CSS-only truncation without renaming)

Please let me know the preferred direction, and I’ll adjust accordingly.

[danbaruka]

I would suggest exploring UX improvements and CSS-only solutions if possible. That way, the full official title remains intact and we avoid any wording changes that could alter the context or formal meaning.

[Ranchhand87]

I would like the DA's to weigh in. Originally this is here as there was drafting for CONTRIBUTING.md changes related to MRP. There are likely other POSM programs that should have suggested documentation updates and thus be listed here on devex.

I value your contribution, Thanks!

Just noting that some gaps should be addressed when we find them, as opposed to making small fixes that have to be done iteratively.

[Ranchhand87]

As is common with other references, If one is shortened, so the other should be too. EX: Dev Ex

[Ranchhand87]

Maybe a question for the DA's is this a single page to explain the site, or something that linkes to multiple guides? Maybe it would read How-To's in the latter example.

[Ranchhand87]

Left some comments, This topic may require more discussion and some pre-build planning. It looks like only 3 Titles were updated, we should envision to an extent how much content there will be and begin adapting text limiting relative to each category.

[Ranchhand87]

@danbaruka Some dependency/deployment changes for you to review in this PR.

[danbaruka]

Hi @chiztechnology
Kindly ensure that package-lock.json or yarn.lock is not part of your changes unless there is a specific reason to update it.

[danbaruka]

Kindly ensure that package-lock.json or yarn.lock is not part of your changes unless there is a specific reason to update it.

[danbaruka]

I would suggest exploring UX improvements and CSS-only solutions if possible. That way, the full official title remains intact and we avoid any wording changes that could alter the context or formal meaning.