The JS sidebar navigation is too confusing (guide + learning docs mixed together)

mdn / content

The content behind MDN Web Docs

https://developer.mozilla.org

Other

9.14k stars 22.45k forks source link

The JS sidebar navigation is too confusing (guide + learning docs mixed together) #31854

Open he110-c0de opened 8 months ago

he110-c0de commented 8 months ago

MDN URL

https://developer.mozilla.org/en-US/docs/Web/JavaScript

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

I find that the file structure and sidebars are both too confusing. When I read the reference, the sidebar links jumps to guide or lean, and can not go back to the reference. I find the file structure mainly contains 3 part : learn, guide and reference, but they are composed together. Where is the code that generate the sidebar indexes? I want to make a clear content index.

What did you expect to see?

A new clear and clean content index.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

Josh-Cena commented 8 months ago

"JavaScript reference" and "Learning JavaScript" are two entirely separate areas, and the former contains "Guide" + "Reference". The "JavaScript reference" sidebar has some "friendly links" to "Learning JavaScript" section docs, but after you navigate, the sidebar changes, which I find far too confusing too. However, if I'm to fix this, I would just delete all "Learning JavaScript" links under "Tutorials", and only keep the links to the "Guide" articles (those that have the same sidebar).

The sidebars you want to edit are under https://github.com/mdn/yari/tree/main/kumascript/macros. I'll caution you that Yari is extremely hard to work with on multiple levels (such as the maintainers taking extremely long to review PRs), so I personally don't send any PRs to them and accept what we have.

I'll also let other maintainers decide since it's a complicated issue.

Josh-Cena commented 2 months ago

I forgot to put down the outcome of a small-group discussion:

We agree it's a problem in general.
We are not sure if it's a content issue, a platform issue, or both.
We are open to exploring ways to improve the sidebars.
The platform is undergoing a major rewrite and the writers will be able to more freely edit the sidebars in the future—or at least, the working mode for the sidebars will change significantly. Therefore we don't feel like it's the best time to reach any kind of decision as the outcome will not be actionable (changes unlikely to land in the platform code) and may not be actionable in the future (because it's no longer implementable, or better solutions are possible).
Therefore we are tabling this to when the platform migration is done.