elastic / elastic/docs-content
Improve scannability of Lens chart type pages
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 21h
- Merged PRs (30d)
- 141
Description
After adding ES|QL patterns in #5446 / #7957, the chart type pages mix two how-tos with a long settings reference. The **On this page** list is noisy (stepper steps plus parallel H2s), and the two create methods sit at the same heading level as best practices, scenarios, settings, and examples.
Raised in review on #7957 ([Natasha](https://github.com/elastic/docs-content/pull/7957#pullrequestreview-4960023661)): the pages are getting lengthy and hard to scan because they mix how-to and reference. Splitting settings into child pages is a possible later step; this issue is the in-page pass first.
## Goal
Make the 13 chart type pages easier to scan without changing what they document. Keep existing anchors so intro choosers and inbound links still resolve.
**Pages:** `explore-analyze/visualize/charts/*.md` (area, bar, gauge, heat map, line, metric, mosaic, pie, region map, table, tag cloud, treemap, waffle).
## Current outline (area as example)
- H2 Build with the point-and-click editor `[build-an-area-chart]` — stepper (steps appear in the ToC)
- H2 Build with an ES|QL query `[build-an-area-chart-with-esql]` — numbered list, not a stepper
- H2 Best practices
- H2 Advanced scenarios
- H2 Settings — definition lists plus nested snippets
- H2 Examples
## Proposed outline
- H2 Create `[build-an-area-chart]` (or a new `create-…` id, with the old ids preserved on the H3s)
- H3 Point-and-click editor — stepper with ToC entries **off**
- H3 ES|QL query — same stepper treatment, ToC entries **off**
- H2 Best practices (shared, after both methods)
- H2 Advanced scenarios
- H2 Settings — consider tables instead of definition lists
- H2 Examples
Intro chooser bullets would then point at the H3s (same explicit anchors as today).
## Work to evaluate
- [ ] **Hide stepper steps from the ToC.** Point-and-click already uses a stepper; those step titles inflate **On this page**. Set the stepper ToC option to false (confirm the current docs-builder syntax; nested-in-tab exclusion is the documented fallback if there is no page-level flag).
- [ ] **Use a stepper for the ES|QL procedure too**, also with ToC off, so both methods look like the same kind of how-to.
- [ ] **One Create H2, two H3 methods.** Point-and-click and ES|QL become siblings under Create. Preserve `[build-…-chart]` and `[build-…-chart-with-esql]` (and table equivalents).
- [ ] **Settings as tables.** Settings sections are long definition lists with snippet includes. Tables are a better scan target now and can be expanded. Try this on one chart page first: term/description columns (`{table}` `:widths: description` may fit), keep snippet reuse, and check that nested includes still read cleanly in cells. If tables cannot hold the current include depth, stop at headings + shorter definition lists rather than forcing it.
## Out of scope
- Splitting settings into child pages (the follow-on Natasha suggested).
- New chart types, new queries, or settings content changes except as needed to reformat.
## Open questions
- Exact stepper ToC opt-out syntax in current docs-builder.
- Whether Create should keep a chart-specific verb ("Build an area chart") or a shared "Create" heading across all 13 pages.
- Whether settings tables should be collapsed by default, and whether snippet-heavy cells are viable.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.