Skip to content

Restructure the a11y test your skills navigation #40503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Conversation

chrisdavidmills
Copy link
Contributor

Description

As part of a general project to improve the structure of the Learn area, I have decided to experiment with changing the navigation with respect to the "Test your skills" articles. Currently, it is a bit weird — all the "Test your skills" articles are linked to at the end of the navigation links, whereas they should be interspersed with the learning articles.

This PR tests the new structure, just changing the Accessibility learn module for now, as it has the smallest number of "Test your skills" articles out of all the core modules.

Specifically, I have:

  • Changed the in-page previous/next links so that the "Test your skills" articles are navigated to after the articles they are testing, in each case.
  • Changed the navigation menu so that the "Test your skills" articles are linked to after the links for the articles they are testing.
  • Removed the "Test your skills!" sections from the learning articles, and the "Test your skills" subtree from the nav menu — we no longer want these to be the ways you get to the "Test your skills" articles.

We might also want to think about the following:

  • The "Test your skills" articles are not linked to from the main module landing page. Should they be?
  • The "Test your skills" landing page still exists, but is no longer linked to from anywhere. Is this a problem?
  • The "Test your skills" articles are still at the same URLs, in the same place in the hierarchy, just linked to form different places. Again, is this a problem?
  • The short titles that appear in the an many are all prefixed with "Test your skills:" to help them stand out, but this does make them a bit longer, and we might want to consider getting them to stand out differently at some point.

Motivation

Additional details

Related issues and pull requests

@chrisdavidmills chrisdavidmills requested review from a team as code owners July 22, 2025 14:36
@chrisdavidmills chrisdavidmills requested review from hamishwillee, dipikabh and bsmth and removed request for a team July 22, 2025 14:36
@github-actions github-actions bot added the Content:Learn Learning area docs label Jul 22, 2025
@chrisdavidmills chrisdavidmills changed the title Restructure the a11y test your skills navigation [Experiment] Restructure the a11y test your skills navigation Jul 22, 2025
@github-actions github-actions bot added the size/m [PR only] 51-500 LoC changed label Jul 22, 2025
Copy link
Collaborator

@hamishwillee hamishwillee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chrisdavidmills TL;DR This is IMO better.


The current design implicitly assumes that testing is separate from learning, and that many uses will skip the learning step, or dip into it "as a bonus" for the cases that they are interested in.

The changes you have made here assume that if you're a learner you really should do those tests, and pushes them into the flow.

I think the core target audience is far more likely to be better served by this change (FWIW I am not in that audience - I read this stuff as a refresher, so prefer not to have the tests in flow).


We might also want to think about the following:

The "Test your skills" articles are not linked to from the main module landing page. Should they be?
The "Test your skills" landing page still exists, but is no longer linked to from anywhere. Is this a problem?

If you think that anyone will want to find the tests as a group then either

  • the main module page should link to the test your skills landing page OR
  • the test your skills links should go onto the module page (and the "Test your skills" landing page should be deleted).
  • There should be no orphan pages.

I "lean" towards having the test your skills links on the main learning page, but it isn't a strong opinion.

The "Test your skills" articles are still at the same URLs, in the same place in the hierarchy, just linked to form different places. Again, is this a problem?

I prefer it this way

The short titles that appear in the an many are all prefixed with "Test your skills:" to help them stand out, but this does make them a bit longer, and we might want to consider getting them to stand out differently at some point.

They need to be highlighted, but why not just a Test: prefix
image

@chrisdavidmills
Copy link
Contributor Author

Thanks for the feedback, @hamishwillee. I'm taking this all as positive — your feelings match my intent for the changes.

I've run out of Mozilla hours this month, but I'll be back working on this in August. This'll also give @bsmth and others time to review and provide feedback if they have anything else to add.

@hamishwillee
Copy link
Collaborator

They are positive. I have reservations, but they are purely selfish because I am not the target audience :-).

@chrisdavidmills
Copy link
Contributor Author

  • There should be no orphan pages.

I've added a link to the "Test your skills" index page on the main "Accessibility" index page, just so it won't be an orphan page. I think any other solution/reorganization will make things a bit too complicated.

@chrisdavidmills
Copy link
Contributor Author

They need to be highlighted, but why not just a Test: prefix

@hamishwillee I've tried doing that for all the "Test your skills" article short titles, and I think it looks fine. Updated in my next commit.

- /Learn_web_development/Core/Accessibility/Multimedia
- /Learn_web_development/Core/Accessibility/Mobile
- /Learn_web_development/Core/Accessibility/Accessibility_troubleshooting
- type: listSubPages
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to think that every single page should be on the sidebar - so even though you link it from the top level, should we have https://developer.mozilla.org//en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills here still (IMO yes)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hamishwillee
Copy link
Collaborator

Looking good. Couple of nits. If I approve and merge this, is the "Experiment" over? I guess I'm asking whether you want me to leave this open for more feedback or if you are happy to continue rolling out the model. IMO it is better, so as long as we continue to the end of rolling this out everywhere I'm happy to merge.

@chrisdavidmills chrisdavidmills changed the title [Experiment] Restructure the a11y test your skills navigation Restructure the a11y test your skills navigation Aug 5, 2025
@chrisdavidmills
Copy link
Contributor Author

Looking good. Couple of nits. If I approve and merge this, is the "Experiment" over? I guess I'm asking whether you want me to leave this open for more feedback or if you are happy to continue rolling out the model. IMO it is better, so as long as we continue to the end of rolling this out everywhere I'm happy to merge.

@hamishwillee I've removed the "Experiment" label ;-)

I'm happy to proceed with this and merge it, having had your feedback.

As you'll see, I'm moving ahead nicely with getting it done in all places. I'll probably have them done by the end of the week.

@dipikabh
Copy link
Contributor

dipikabh commented Aug 5, 2025

Hi @chrisdavidmills, I've taken a look now. I like that the tests are now part of the learning flow - this is great!

That said, I'm missing the visual cue in the sidebar. To me, the previous drop-down icon used for grouping the tests helped the tests stand out in the sidebar.
Thinking about how we could visually convey the interspersed tests in the "new sidebar" - I wonder if we can have a short title along these lines (or if you any other suggestions for a better emoji):
short-title: "🎯 Test: CSS/JS a11y"

True, like Hamish said, we're not the audience, so we're making assumptions about what might work better in their learning process. We do get learners from time to time on Discord. Maybe we could ask a few where they prefer to see the tests - in the flow or at the end. (we could even share this change in our next community call and see what folks think.)

I like the addition of "Test your skills" to the module landing page.

@chrisdavidmills
Copy link
Contributor Author

Hi @chrisdavidmills, I've taken a look now. I like that the tests are now part of the learning flow - this is great!

@dipikabh Yay!

That said, I'm missing the visual cue in the sidebar. To me, the previous drop-down icon used for grouping the tests helped the tests stand out in the sidebar. Thinking about how we could visually convey the interspersed tests in the "new sidebar" - I wonder if we can have a short title along these lines (or if you any other suggestions for a better emoji): short-title: "🎯 Test: CSS/JS a11y"

This is a really good point — I was also worried about them getting lost in the sidebar. In terms of what emoji to use, I can see the logic of using the target emoji to indicate a test or challenge, but I tried it, and I was a bit concerned that it is too hard to tell what it is, especially in the sidebar.

To move forward on this, my latest commit adds a different emoji to each "Test your skills" short title, so you can have a look and see if you like any of these better than the target:

  • 🚩: indicates challenge, goal, or end of stage; maybe also a bit hard to see, especially in dark mode.
  • 💡: indicates challenge, "your turn", or "thought required"
  • ⭐: indicates challenge or reward; maybe not as obvious as the other options, but it stands out very clearly.

True, like Hamish said, we're not the audience, so we're making assumptions about what might work better in their learning process. We do get learners from time to time on Discord. Maybe we could ask a few where they prefer to see the tests - in the flow or at the end. (we could even share this change in our next community call and see what folks think.)

I honestly can't see how the majority of learners would have a more effective learning experience by having all the challenges bunched up at the end, rather than interspersed throughout the learning articles. And, even if they say they prefer them at the end, I think the temptation is much higher to skip them rather than work your way through them all.

I surveyed several learning resources, and they overwhelmingly have their tests interspersed in small chunks.

Also, the way I've got it in these test PRs, we have the index page linked at the end anyway, so you can revisit them in a group if you want to.

I like the addition of "Test your skills" to the module landing page.

Cool!

Copy link
Collaborator

@hamishwillee hamishwillee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Changes you made since my last look are good.

FWIW I much prefer the target followed closely by the star. The other two don't do it for me.

@chrisdavidmills
Copy link
Contributor Author

Thanks. Changes you made since my last look are good.

FWIW I much prefer the target followed closely by the star. The other two don't do it for me.

I'd like to get some other opinions here. I think that the target is conceptually good, but I am still concerned that it is hard to see what it is, especially in dark mode.

@dipikabh
Copy link
Contributor

dipikabh commented Aug 8, 2025

I like the flag 🚩 - it symbolizes a milestone.
It's a good enough marker (works for me at least) in dark mode.

I can bring up the options for a team vote on Monday and get back to you. Since Ruth and Vadim have been working on the new design system, they might have a better idea of what'll work in the new scheme or maybe even other suggestions.

@chrisdavidmills
Copy link
Contributor Author

I can bring up the options for a team vote on Monday and get back to you. Since Ruth and Vadim have been working on the new design system, they might have a better idea of what'll work in the new scheme or maybe even other suggestions.

That would be wonderful, thanks @dipikabh!

@dipikabh
Copy link
Contributor

@chrisdavidmills, I have an update for you from our discussion in the team meeting.

The long-term solution would be to use an icon in the sidebar instead of a hardcoded emoji (the icon will be added to the end of the text, not the beginning like I was suggesting).
And since the test pages already have a page type, learn-module-assessment, that'll make it easier to add the chosen icon to the sidebar for all such pages in one go once the new front end is released.

We're using Lucide icons in the new front end. There was a suggestion to use book-open-check for the test pages.

So for now, we can probably skip adding any emoji, land the pages with the new navigation as-is, and follow up after the new front end is officially released, it shouldn't be long now.
(If you'd like, I imagine you could already open an issue to add an icon for the test pages – with the caveat of following up after fred is launched. OR we can wait and follow up with the engineering team after the launch.)

Copy link
Contributor

@dipikabh dipikabh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me also leave an approval to unblock you from merging

@chrisdavidmills
Copy link
Contributor Author

@chrisdavidmills, I have an update for you from our discussion in the team meeting.

The long-term solution would be to use an icon in the sidebar instead of a hardcoded emoji (the icon will be added to the end of the text, not the beginning like I was suggesting). And since the test pages already have a page type, learn-module-assessment, that'll make it easier to add the chosen icon to the sidebar for all such pages in one go once the new front end is released.

We're using Lucide icons in the new front end. There was a suggestion to use book-open-check for the test pages.

So for now, we can probably skip adding any emoji, land the pages with the new navigation as-is, and follow up after the new front end is officially released, it shouldn't be long now. (If you'd like, I imagine you could already open an issue to add an icon for the test pages – with the caveat of following up after fred is launched. OR we can wait and follow up with the engineering team after the launch.)

Great stuff, thanks @dipikabh! I have removed the emojis, and will merge these PRs for now. I'll then file an issue to request that the devs add the relevant lucide icon to those article short titles and titles after the fred launch is done.

I think book-open-check is a good choice too.

@chrisdavidmills
Copy link
Contributor Author

@dipikabh fred issue filed here: mdn/mdn#710

@chrisdavidmills chrisdavidmills merged commit 89e8e67 into mdn:main Aug 12, 2025
8 checks passed
@chrisdavidmills chrisdavidmills deleted the restructure-a11y-test-your-skills-nav branch August 12, 2025 16:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:Learn Learning area docs size/m [PR only] 51-500 LoC changed
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants