docs: fill four gaps found in a customer-facing feature sweep - #11565
docs: fill four gaps found in a customer-facing feature sweep#11565keydunov wants to merge 1 commit into
Conversation
…s-view control connect, and multi-anchor comparisons - dbt.mdx: the dbt-sync trigger now accepts a `ref` override and exposes status/result/cancel endpoints for CI gates (CUB-3777) - charts/index.mdx: note the new warning when a query change breaks the applied chart type (CUB-3808) - dashboards/widgets/controls.mdx: document the connect prompt for cross-view charts and the new "Suggested mapping" state (#13630) - workbooks/querying-data.mdx: clarify that the same offset comparison can be applied under more than one time-dimension anchor (CUB-3459)
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Claude finished @keydunov's task in 1m 19s —— View job Docs review — no blockers, 2 medium + 1 nit (all in
|
| # | Severity | File | Issue |
|---|---|---|---|
| 1 | Medium | docs/integrations/dbt.mdx:407-410 |
ref is described but never shown — no HTTP method, no indication whether it's a query param or JSON body field. Not actionable as written. (thread) |
| 2 | Medium | docs/integrations/dbt.mdx:415-419 |
.../dbt-sync/{syncJobId} never states it's relative to the trigger URL; status values are only partially enumerated, so a poll loop has no documented exit for a cancelled job. (thread) |
| 3 | Nit | docs/explore-analyze/dashboards/widgets/controls.mdx:111 |
Single ~70-word paragraph carrying five distinct facts (why it isn't automatic, the banner, Review…, Save/Dismiss, Undo). The style guide asks for short paragraphs; splitting after "…isn't necessarily the same dimension." would read better. Purely stylistic. |
Checked and fine
charts/index.mdx:18— placed correctly under Selecting a chart type, directly after the sentence about configuration being preserved across query edits. Reads as a natural continuation.workbooks/querying-data.mdx:222-224— the multi-anchor clarification extends the existing sentence rather than starting a new block; correct call for a one-fact addition.controls.mdxtable row — wording of Suggested mapping correctly distinguishes "found but not applied" from the adjacent Manually mapped / Can't map automatically states.- Plan gating —
dbt.mdxalready carries its Premium-and-above<Note>; the other three pages inherit theirs from context. Nothing new needed. - No images committed; the existing
ucarecdn.com<Frame>above the new dbt content is untouched.
Not verified
The four behaviors trace to cubejs-enterprise PRs (#13972, #13942, #13630, #13859), which aren't in this repo — I could not confirm the described behaviors against the implementation. Findings 1 and 2 are the places where that gap actually matters, since both hinge on API shape a docs reader has to type verbatim.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| The trigger call accepts an optional `ref` — a branch or tag in your dbt repository — | ||
| to sync from for that call only, without changing the branch saved on the | ||
| integration. Use it in a pull request pipeline to test the ref under review before it | ||
| merges. |
There was a problem hiding this comment.
The ref parameter is described but not shown — a reader can't act on this without knowing where it goes (query string vs. JSON body) and what the trigger's HTTP method is. Neither is stated anywhere on the page, and the screenshot above only shows the URL.
Worth one short concrete line, e.g. POST .../dbt-sync?ref=my-branch or a {"ref": "my-branch"} body — whichever matches the implementation.
| | Call | What it does | | ||
| | --- | --- | | ||
| | `GET .../dbt-sync/{syncJobId}` | Returns the sync's current `status`. Poll it until `status` reaches `COMPLETED` or `FAILED`. | | ||
| | `GET .../dbt-sync/{syncJobId}/result` | Once `status` is `COMPLETED`, returns the generated cube files and cube count. | | ||
| | `DELETE .../dbt-sync/{syncJobId}` | Cancels a sync that's still running — for example, when a newer push supersedes it. | |
There was a problem hiding this comment.
Two small things in this table:
- The
.../prefix is doing a lot of implicit work. The paragraph two above says the trigger URL is in the settings card, but nothing states that these paths are relative to that same URL. A half-sentence lead-in ("…using the same endpoint URL shown above:") would remove the guesswork. statusis only partially enumerated —COMPLETEDandFAILEDare named as terminal, but a poller also needs to know what it will see in the meantime (PENDING/RUNNING/whatever the API returns), and whether cancellation surfaces as a distinct terminal status. As written, "poll untilstatusreachesCOMPLETEDorFAILED" could loop forever on a cancelled job.
2 participants
Check List
Description of Changes Made
Routine sweep of recent
cubejs-enterprisemerges cross-checked against docs-mintlify turned up four shipped, customer-facing behaviors with no documentation. All four are small, surgical additions to existing pages:docs/integrations/dbt.mdx— dbt Sync's public trigger endpoint now accepts an optionalrefto sync a specific branch/tag for one call (e.g. testing a PR branch before merge), and the previously browser-only status/result/cancel operations are now exposed on the same public, deployment-scoped API so a CI pipeline can start a sync, poll it, and fail the build on error (cubejs-enterprise#13972, CUB-3777).docs/explore-analyze/charts/index.mdx— Cube now warns when a later query edit leaves the applied chart type unable to render the result, naming the chart type and offering to undo the edit or pick a different type (cubejs-enterprise#13942, CUB-3808).docs/explore-analyze/dashboards/widgets/controls.mdx— adding a chart from a different semantic view than the dashboard's existing controls now surfaces a suggestion prompt (Review… / Dismiss, with Undo after connecting) instead of leaving the chart silently unconnected; added the corresponding "Suggested mapping" state to the mapping-states table (cubejs-enterprise#13630).docs/explore-analyze/workbooks/querying-data.mdx— clarified that the same period-comparison offset can now be applied under more than one time-dimension anchor in the same query, each producing its own derived columns (cubejs-enterprise#13859, CUB-3459).No new pages were needed — each fits naturally into an existing section.
🤖 Generated with Claude Code
Generated by Claude Code