docs: describe how the best-fit chart type is recommended - #11567
docs: describe how the best-fit chart type is recommended#11567igorlukanin wants to merge 2 commits into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Claude finished @igorlukanin's task in 1m 57s —— View job Docs review — 0 blocking, 3 medium, 4 low. Prose is clear and well-structured; main gaps are terminology (
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| | **Stacked bar** | One measure split by two categories, the first up to 12 values and the second up to 10 | | ||
| | **Heatmap** | One measure split by two larger categories that fill enough of the grid to be worth drawing | | ||
| | **Bar** | One measure across a few categories with short labels | | ||
| | **Horizontal bar** | The same, where the labels are long or the categories too many for a vertical axis | |
There was a problem hiding this comment.
Stacked bar and Horizontal bar are presented here as if they were chart types, but neither appears in this page's own list at lines 8–18 — they're variants of Bar (bar.mdx has ### Stacked and ### Horizontal). A reader scanning this table has nowhere to click and no way to map these names onto the type list at the top of the same page.
Suggest naming them as variants, e.g. "Bar (stacked)" / "Bar (horizontal)", and linking to Bar. Same applies to the prose on line 83.
| On a report that has no chart yet, a recommendation Cube is confident about is applied for you, and | ||
| the report names the rule it followed — for example, *Applied Line — a measure over time*. Anywhere | ||
| else the recommendation is only outlined, never applied. |
There was a problem hiding this comment.
"report" isn't a term in the product taxonomy in docs-mintlify/CLAUDE.md (Account → Deployment → Workbook → Tab → Dashboard builder → Widget; plus Dashboard), and it appears nowhere else in docs/explore-analyze/charts/. This PR introduces it as a new noun in three places (lines 28, 29, 80).
If the surface is a workbook tab, say "a tab with no chart yet"; if it's a dashboard widget, say widget. Whichever it is, the reader needs to know which UI this auto-apply behavior fires in — right now "report" reads as a fourth, undefined surface.
| Table's conditions are disqualifiers rather than a last preference: a query that meets any of them | ||
| has no chart encoding that reads well, so the table is the honest answer. Maps are the exception — | ||
| a map has no category axis to crowd, so a choropleth over 40 regions is normal rather than | ||
| unreadable. |
There was a problem hiding this comment.
This paragraph contradicts the table it follows. Line 50 says the conditions are checked "in order" with first match winning, and Table is listed last — but "disqualifiers rather than a last preference" means they're evaluated before the others, otherwise a 4-dimension query would match Bar or Stacked bar first and never reach Table.
Either move the Table row to the top of the table (and say the first row is a disqualifier gate), or drop the "in order" framing and describe the check as "disqualifiers first, then the ordered preferences."
| labels are, and how many rows came back. Nothing is sent anywhere and nothing is saved — the | ||
| suggestion lasts for the current session only. |
There was a problem hiding this comment.
"Nothing is sent anywhere" reads as a privacy guarantee but the thing being described is derived from a result set that already came back from the server, so a reader can't tell what claim is being made — that the recommendation runs client-side? that no telemetry is emitted? Suggest saying the specific thing ("the recommendation is computed in your browser and isn't persisted"), or dropping the sentence: nobody asked, and an unclear privacy claim is worse than none.
| Automatic application on an empty report clears a higher bar than the outline does. It happens only | ||
| for Map, KPI, Line, Scatter and vertical Bar, only when no threshold sits within 20% of the observed | ||
| value — so a row either way would not change the answer — and never on a truncated result. Stacked | ||
| bar, heatmap, horizontal bar and pie are offered but never applied for you: stacking asserts that | ||
| the parts compose the whole, which Cube cannot verify from a filtered result, and the others turn on | ||
| a judgment of Cube's own. |
There was a problem hiding this comment.
This paragraph is the section's highest-maintenance content and its lowest reader value. "No threshold sits within 20% of the observed value" is an internal confidence heuristic — a business user can't act on it, can't observe it, and it will silently go stale the first time the margin is retuned. The closing rationale ("stacking asserts that the parts compose the whole… the others turn on a judgment of Cube's own") is design justification, not usage guidance.
docs-mintlify/CLAUDE.md asks for the shortest version that answers "how do I use this?" I'd keep the actionable half — auto-apply happens only for Map, KPI, Line, Scatter and vertical Bar, only on a confident match, and never on a truncated result — and cut the rest. Same instinct applies to line 45's "tuned by us": documenting exact tuned constants invites drift between the page and the rule table.
|
Claude finished @igorlukanin's task in 1m 16s —— View job Re-review of the new commit — 0 blocking, 2 medium, 3 low. The Pie fix lands cleanly; four prior threads still apply, and the new Pie paragraph is longer than the behavior it describes.Full review
What changed in
|
| | **Heatmap** | One measure split by two larger categories that fill enough of the grid to be worth drawing | | ||
| | **Bar** | One measure across a few categories with short labels | | ||
| | **Horizontal bar** | The same, where the labels are long or the categories too many for a vertical axis | |
There was a problem hiding this comment.
Dropping the Pie row resolves the unreachability problem, but the vagueness half of my earlier comment survives: these three rows are the only qualitative ones in a table that otherwise cites exact numbers (12 / 10 / 30 / 5,000), and the section above defines 12 and 16 precisely so the reader arrives expecting them.
- "a few categories with short labels" — presumably ≤ 12 values and mean label < 16 characters, but the row doesn't say, and the reader has just been handed both numbers.
- "the categories too many for a vertical axis" (line 61) — same number, unnamed.
- "fill enough of the grid to be worth drawing" (line 59) — no stated criterion at all; a reader cannot predict when Heatmap wins over Stacked bar.
Naming the numbers here costs a few words and makes the table self-consistent.
| Automatic application on an empty report clears a higher bar than the outline does. It happens only | ||
| for Map, KPI, Line, Scatter and vertical Bar, only when no threshold sits within 20% of the observed | ||
| value — so a row either way would not change the answer — and never on a truncated result. Stacked | ||
| bar, heatmap and horizontal bar are offered but never applied for you: stacking asserts that the | ||
| parts compose the whole, which Cube cannot verify from a filtered result, and the others turn on a | ||
| judgment of Cube's own. |
There was a problem hiding this comment.
Re-raising on the rewritten paragraph (my earlier thread went outdated when Pie was dropped from the list, but the substance is unchanged).
"no threshold sits within 20% of the observed value" is an internal confidence constant — a business user can't observe it, can't act on it, and it goes stale the first time the margin is retuned. The closing rationale ("stacking asserts that the parts compose the whole… the others turn on a judgment of Cube's own") is design justification rather than usage guidance.
docs-mintlify/CLAUDE.md asks for the shortest version that answers "how do I use this?" The actionable half — auto-apply happens only for Map, KPI, Line, Scatter and vertical Bar, only on a confident match, never on a truncated result — is worth keeping; the rest I'd cut. Same instinct for "tuned by us" on line 45.
1 participant
Summary
The chart picker now suggests one best-fit chart type for the current query, and applies a high-confidence one on a report that has no chart yet. Nothing described how it decides, so this documents the conditions in business-user language on the existing Chart types overview.
Covers what the recommendation reads, the ordered conditions, when it deliberately stays quiet, and the higher bar that automatic application clears.
Thresholds are cited to Draco (Moritz et al., Formalizing Visualization Design Knowledge as Constraints, IEEE VIS 2018). The two numbers that are Cube's own rather than Draco's — the 16-character mean label length and the 5,000-row cap — are marked as ours.
Test plan