reconsider backend, CMS, and migration guides' navs item order for better UX

[olets]

📋 Explain your issue

The CMS Guides Nav https://docs.astro.build/en/guides/cms/ is three lists:

1. guides with "good content", in arbitrary order determined by the maintainers
2. non-stubs, alphabetically
3. stubs, alphabetically

I've spent a lot of time in the Astro docs' CMS Guides section over the last month and all along assumed the order was either random or by date contributed. It wasn't usable, but the browser's in-page search was my friend.

Today I looked at the source https://github.com/withastro/docs/blob/main/src/components/CMSGuidesNav.astro, and learned about its three sections.

IMO listing all guides alphabetically would be a better UX:

• With over 30 CMSes listed, compared to the 10 which were listed when the nav was released, it's hard to scan and answer the question "is there a guide for ___". Alphabetical is easier to scan.

IMO keeping the existing order but surfacing the separate lists would not be an improvement:

• It's not clear what makes the three "good" guides best. It's not clear what benefit there might be to separating those three
• The non/stub distinction is relevant to would-be guide contributors, while the nav is primarily for docs readers
• There is some really strong third-party content linked on the guides pages, so stubbiness is not an indicator of how useful it will be for a dev to click on the nav link.

I'm up for contributing an update to the CMS Guides Nav if you all decide to change it.

[sarah11918]

Hi @olets ! You're absolutely right and this is something I've been looking to update for a while now!

Fun fact: when we started this section, we wrote two full (non-stub) guides and one stub. Over time, the community contributed more and more guides. Originally, when there were very few, we presented the guides in full-then-stub order thinking that it was more helpful for people to see actually full written guides, and for more popular options. Now, it's just a big mess. 😅

I think it does make sense to just list them all alphabetically now. Would absolutely welcome a PR to gut that, and just go alphabetical! Would still need reviewing by the rest of the team, but I think it's the only sensible thing right now!

[olets]

Great!

I see that https://docs.astro.build/en/guides/backend/ and https://docs.astro.build/en/guides/migrate-to-astro/ use the same sorting. Shall I update those front ends too?

[at-the-vr]

sounds good to me 👍 only thing I will ask is keeping them in separate PRs for review ease 😄

[olets]

Close when these merge or close:

• Migration guides nav: sort alphabetically (part of #8860) #8896
• Backend guides nav: sort alphabetically (part of #8860) #8897
• CMS guides nav: sort alphabetically (part of #8860) #8898

[sarah11918]

Closing! Thank you for your service, @olets ! 🫡

[olets]

@sarah11918 great!

You may now be able to remove the remaining traces of "stubs" from the back end. The frontmatter value isn't used on the front end. Don't know if the appearances in ./scripts are needed. Etc.

[sarah11918]

Thanks for pointing that out! Happy if you'd like to explore that further in the code. I do know that at least some of those guides use a different layout when they are marked as a "stub" (There's a notice on the page that "This is only a stub -- consider adding to this guide or links to other resources") but I'm not sure whether there's a separate stub layout for every type of guide.