[docs] Revise the Getting Started docs

[markcaron]

Discussed in https://github.com/orgs/RedHat-UX/discussions/1150

^{Originally posted by nikkimk July 19, 2023}
@Nouveau and I were discussing the Getting Started docs and wondered if we need to think about the audience for the docs, as we have several audiences to consider: design system consumers versus contributors and designers versus developers.

We took a look at how other design system docs are organized:

• Carbon organizes into Designing, Developing, Contributing, and Migrating
• Patternfly organizes into Contribute->Design, Contribute->Develop, Get Started->Contribute, and Get Started->Design and Develop under it.
• Patternfly elements organizes into Get started and Develop
• Material design organizes into Get started->Design, Get started->Develop, and Develop

We're thinking we should reorganized this content something like this:

• Get started
  • For designers
    • Overview
    • Design system kit
    • FTS
    • Icons, etc.
  • For developers
    • Overview
    • Using npm
    • Using CDN**
    • React wrappers* coming soon
    • Vue wrappers* coming soon
• Contribute***
  • Overview
  • Bugs and requests
  • Documentation
  • Components
  • Icons
  • Patterns

**Link to VPN for Red Hat-specific Implementation
**Contribute page see Carbon’s contributing section

[bennypowers]

Follow up from Aug 7 office hours:

1. Develop a graphical motif to represent the concepts 'token', 'element', and 'pattern'
   • these graphical identities should be legible at large (landing page) and small (header nav) sizes
   • think "atomic design" with h/t to Brad Frost
2. Add a "Components" page to the top-level nav
   • Landing page with three graphic cards briefly explaining and linking to tokens, elements, patterns
   • Add a section to this page "Why not call 'elements' 'components'"?
3. Add detailed explanations of the concepts 'token', 'element', and 'pattern' to their respective overview pages
4. Add graphic cards with links and motifs to "get started" with explanations of 'tokens', 'elements', and 'patterns'
5. Add breadcrumb-like "you are here" maps to each page's header
   • utilizing the graphical motif developed in step 1

In addition, we should add a page (perhaps under foundations? but the exact location TBD) with detailed guidance on colour context

cc @coreyvickery for your consideration, and with thanks to @nikkimk and @markcaron for leading the conversation

[bennypowers]

one idea for a strech goal:

In addition to the three cards on /components, we could also offer a decision tree ui, like

"I want to [build a page|contribute to rhds]" > "I need a [small ui component|complex ui item]" > "I need a [form control|layout container]" > rh-card docs

[markcaron]

Breaking down Tokens, Elements, Patterns as our "ATOMIC" building blocks in the same way Brad illustrates this.

[marionnegp]

Add detailed explanations of the concepts 'token', 'element', and 'pattern' to their respective overview pages

Would this info work better under the About section? I see tooling info going in the Get Started section and any conceptual info under About. Of course, we could tell people to check the About pages for more info about our terminology.

[bennypowers]

we also need a thorough explainer on the context system. perhaps in a separate effort

[marionnegp]

@bennypowers, @coreyvickery and I are updating the Color page. Do you think it makes sense to add there with theming information?

[bennypowers]

in general i think the balance between designer-oriented and engineer/front-end-oriented content on ux is off.

We need to set the balance so that both groups can easily find the info they need.

Use of color as a design component while it is a front-end concern, IMO it makes more sense for designers to make those decisions higher up the chain. our goal should be to reduce the number of occasions in which front-end developers have to think about specific colour values as much as possible. Instead, front-end devs should be thinking in terms of named semantic colour tokens

From that perspective, we need comprehensive docs on our colour context system

[marionnegp]

I've started writing content for the Designers page in this Google doc.

[marionnegp]

@RedHat-UX/developers, I started a Google doc for the Get Started: Developers page. Most of this info is copied from our README files and lightly edited. I've added highlighted placeholder text to call out sections that need content. Feel free to edit this doc.

[markcaron]

@nikkimk @bennypowers @brianferry do you all mind looking at Marionne's doc above and providing feedback?

[marionnegp]

The Overview and Designers pages are live. The Developers page is in a draft PR.

[marionnegp]

@markcaron @hellogreg, Get Started pages for designers and developers are up. Should I keep this issue open until we have a page for contributors?

[marionnegp]

@markcaron, since we're just waiting on contributor docs, can I close this in favor of #1175?

[bennypowers]

Closing in favour of #1175