docs: draft proposal for improving structure clarity

[rodet]

During the previous FED Academies, I've had quite a few discussions around the Carbon documentation.

While we should expect developers to read through everything, they do not. And many key elements are unclear to them:

• The different libraries in the ecosystem (PALs)
• The different level of support for different libraries (official, community)
• What is the IBM Design Language (you can go through most of the docs without reading much about it)

I found a few things:

• There are very good pages, like in "All about Carbon", that try to explain the background and build a mental model for the user, but it should be much more "in your face". I even hadn't looked at that section before today, because who wants to learn all about Carbon? I just want the essentials. People are overloaded with information and filter out what doesn't look essential.
• Migrating starts to be a wrong term, more correct would be upgrading. Migrating would be from a non-Carbon ecosystem. Having things like the Grid explained is much more important, because developers don't know they have to learn about it, so we have to try to make it clearer
• The documentation is scattered between Gatsby, README, packages, Storybook and Stackblitz. I don't have a magic fix but we should be clearer / more visual about it. So I added more explanations on the front-page to try to clarify this. We might want to be a bit more visual as well.
• Too many devs don't know about the design language and they write countless useless lines of CSS! This is a huge waste. We need to make the relationship more straightforward.

Instead of complaining, here is an example draft that tries to improve on this. The wording is probably less than perfect, the design even less, but it should be a good discussion start.

Let me know your feedback, or just book a meeting to discuss!

Changelog

New

• More cross-links and cards for overview and quicker, easier, clearer reach
• More mentions of the design language, especially related to the grid
• More links to the ecosystem libraries
• More flagging with official / community packages

Changed

• Nav: "All about Carbon" → "Introduction"; "Migrating" → "Upgrading"
• Content: Should we change "Carbon components", "Carbon XY" etc to "Carbon core XY"? More clarity might defuse the confusion as whole teams are not aware that there are such things as Carbon for IBM Products.

Again, this PR is more to be seen as a set of ideas and base for discussion. Let me know what you think.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
carbondesignsystem	❌ Failed (Inspect)			Feb 20, 2025 3:50pm

[github-actions]

Deploy preview successfully published at https://4482--carbondesignsystem.netlify.app with commit (d789385)