elastic / elastic/docs-content

Improve scannability of Lens chart type pages

Open
#8,123 1 comment 0 reactions 1 assignee Claimed by @florent-leborgne View on GitHub
enhancement Feature: Visualizations Team:SKI
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.