[Meta] Improve documentation examples

[weronikaolejniczak]

This Meta issues captures a theme of work we would like to perform, rather than a clearly defined project with a defined end goal. For now, we're going to use it capture areas for improvement for potential prioritization.

Goal

Improve documentation examples so that they:

• Are generally more understandable and useful
• Are additive -- start with most basic usage and build upon it
• Capture the most common use cases based on real usage in Kibana
• Display usage that we want to encourage, and do not unintentionally promote non-ideal usage
• Are not redundant
• Are not broken
• Are interactive when possible
• Consider a11y related examples

[!NOTE]
This Meta issue is scoped to "Examples, but frankly, while reviewing examples it's an oppurtunity to consider other things as well:

We can and should be linking to available Patterns content when available. For instance, a Paging example in Basic table should also link to the Paging pattern for more information. The inverse of that is true as well.

Additionally, if there are equivalents in Kibana that folks should be aware of, we should highlight that in our docs. For instance, the Datagrid docs should likely mentioned the UnifiedDataTable in Kibana.

This could expand beyond just examples, some components simply need more written detail, like in this PR.

This page was updated recently and illustrates both linking to Patterns and highlights guidance for Kibana: https://eui.elastic.co/docs/utilities/error-boundary/

Problem Statement

Specific problem areas of note:

• Both Tables and DataGrid suffer from a common problem:
  • There is no basic, stripped down, MVP getting started example to easily copy and paste from. Ideally, examples here are additive. They start with the most basic example possible and build upon it conceptually. We should build upon it with
  • The examples all contain a ton of setup code with faker data, etc. that really distracts from illustrating the core concepts.

Example of additional interactivity which was beneficial: https://github.com/elastic/eui/pull/8440#pullrequestreview-2689811289

(Please edit this issue with more examples as we find them)

Supporting Data

There we many comment related to documentation in the 2024 Survey:

Things people would change:

I would like to see the code examples be simpler and additive from the first example to the more complex one. Or maybe annotated code examples. Looking at a basic component provides one way of building it, but looking at the same with 3 features added to it presents a different way and not clear where it all fits together. This presents a bigger barrier of entry for those who want to try and code more prototypes.
Designer - Search

"The documentation could use a more frequent update, because new decisions around implementation and stretching component boundaries are made all the time(with the EUI team) but documentation isn't updating as quickly and you really need to be aware of slack and emails all the time."

• Designer - Security

"Sometimes we are missing some use cases ( e.g. having a cell variant with text, description, badges. This is what we have in the Dashboards pages)"

• Designer - Observability

"more ready to use examples"

• Designer - Security

"Sometimes I wish the docs had more specific examples of adavanced usages. However, when I don't find something in the docs, I usually look for examples inside Kibana."

• Engineer - Platform

"sometimes the documentation across components is inconsistent or missing key details "

• VP

"Clearer documentation for some of the sub-components. A deep dive into the API for all components would be great."

• Engineer - Platform

"I like the docs side of https://eui.elastic.co/ better than going through the .d.ts files in node modules. I feel like there is more context and information there."

• Engineer, Search