[Docs] Contributing guide on eui.elastic.co

[JasonStoltz]

Is your feature request related to a problem? Please describe.

One of the main goals of the new site is to give designers an easy way to contribute UX guidelines and patterns, fostering ownership and empowerment across UX teams. To support consistent, efficient UI development at Elastic, we need more content - and a simple, accessible workflow to create it, especially for designers who may not be comfortable using GitHub directly.

Currently, contributors must rely on:

• The reference guide
• Instructions for running docs locally

These resources are helpful but not easily discoverable or optimized for non-technical contributors.

Describe the solution you'd like

Ideally, we do the following:

1. Move the reference guide to a "Contributing to docs" section directly in eui.elastic.co. This keeps it close the content and easily discoverable.
2. Add a simplified step-by-step guide for someone who likely doesn't have EUI checked out locally already that explains how to checkout the project, set it up, run docs, make edits, and then create a PR.
3. As part of the previous, include a section that explains how to make quick edits without checking the project locally.
4. A dedicated guide for how to author a new pattern.

Possible IA:

Getting Started/
├── Setup
├── Theming
├── Accessibility
├── Testing
└── Contributing to EUI Docs/
    ├── Quick Start (How to make edits, with and without setting up the project locally)
    ├── Reference (from GitHub wiki)
    └── Writing Patterns

On the Patterns page, we should link to "Contributing to EUI docs".

Describe alternatives you've considered N/A

Desired timeline We should prioritize this quickly.

Additional context N/A

[JasonStoltz]

CC @formgeist, since I believe you spoke with @tkajtoch about this. Feel free to add any more thoughts.

[ryankeairns]

Notes:

• The Usage section on component pages is quite similar to patterns, by definition, but seem to be component specific
• The top-level Patterns area of the site is probably best suited for cross-cutting patterns that are not component specific (i.e. involve the combination of multiple components)
• We could also bubble up (i.e. re-use) Usage content into the Patterns area
• Guidelines also have two sort of types... in the old docs site, there were Guidelines tabs and we have UX Guidelines as docs for product-level guidance

...we need to get more concrete and have fewer types of guidance...

---

@yanwalton and I discussed this recently and wondered if the delineation is:

Definitions

Guidelines Guiding principles and best practices ensuring consistency and quality.

They answer "How to use it correctly," providing usage instructions, do's and don'ts, accessibility guidelines, and best practices. Benefits include consistency, quality, and efficiency.

Patterns Reusable solutions combining components to solve design problems.

They answer "How to solve this problem," showing component combinations, layout, user flow, interaction, and code examples. Benefits include efficiency, scalability, and consistency.

Audience and Ownership

Design System Team Creates and maintains base guidelines and patterns for general use, focusing on external users and public documentation. Responsibilities include developing base guidelines/patterns, maintaining public documentation, and providing external support.

Focus areas include baseline use cases, accessibility, and cross-platform consistency.

Solution Teams Extends the design system for specific project needs and internal users. Responsibilities include creating product-specific guidelines/patterns, maintaining private documentation, and providing internal support.

Focus areas include specific use cases, customization, and solution-level consistency.

[JasonStoltz]

@weronikaolejniczak As we discussed over Slack.

After giving it some thought, maybe it is, in fact, best to keep this content in https://github.com/elastic/eui/tree/main/wiki/contributing-to-eui/documenting.

That way, the content still remains discoverable for folks navigating the repository and contributing content.

In that case, I would change my guidance to:

Getting Started/
├── Setup
├── Theming
├── Accessibility
├── Testing
└── Contributing to EUI Docs/ -- link to https://github.com/elastic/eui/tree/main/wiki/contributing-to-eui/documenting/quick-start.md

We can still plan to add the same content and sections as discussed, this just ensures it's easily discoverable from both Github and Docs.

This Epic is large, I'd recommend starting small with a simple quick-start.md in the short term, linked from docs.

[github-actions[bot]]

👋 Hi there - this issue hasn't had any activity in 6 months. If the EUI team has not explicitly expressed that this is something on our roadmap, it's unlikely that we'll pick this issue up. We would sincerely appreciate a PR/community contribution if this is something that matters to you! If not, and there is no further activity on this issue for another 6 months (i.e. it's stale for over a year), the issue will be auto-closed.

[weronikaolejniczak]

Still likely needed, not sure when we'd prioritize it.