Skip to content

Rewrite Merge Queue overview for skeptical CI engineers#63

Open
samgutentag wants to merge 5 commits into
mainfrom
sam-gutentag/merge-queue-overview
Open

Rewrite Merge Queue overview for skeptical CI engineers#63
samgutentag wants to merge 5 commits into
mainfrom
sam-gutentag/merge-queue-overview

Conversation

@samgutentag
Copy link
Copy Markdown
Member

@samgutentag samgutentag commented May 21, 2026

Summary

Ground-up rewrite of merge-queue/merge-queue.mdx, triggered by Eli's feedback on 2026-05-21:

  • "Big three items don't make sense or are outright lies"
  • "Calls out Nx/Bazel but not other build systems"
  • "Not selling — no clear audience, layout sucks"

What changed

  • Hook replaced. Marketing-style intro ("enterprise upgrade", "fire and forget", "cut CI costs up to 90%") swapped for a two-paragraph mechanic-first intro that defines a merge queue, names predictive testing as the universal baseline, and identifies the three mechanics Trunk layers on top.
  • Three stacked sections → 3-column Tiles for batching / parallel queues / anti-flake protection. Each tile is a one-line description + icon + link to the deep page where the Vidyard / iframely visuals already live.
  • New "When does this make sense?" decision tree maps symptoms (CI bill climbing, monorepo with non-overlapping lanes, flaky tests, GHMQ choking) to mechanics in recognition voice.
  • "More to dial in" section adds Direct merge to main (the only architectural optimization in the settings UI that wasn't already represented at the top), Priority merging, Predictive testing internals, and Testing concurrency.
  • Stripped factually wrong claims that were on the old page: "Automatic quarantine of flaky tests" (wrong product — that's Flaky Tests), "Batch up to 100 PRs" (no such limit; default is 4, recommended max is small), "cut CI costs up to 90%" (the batching sub-page documents 50–70%).
  • "Native Bazel/Nx integration" → "Bazel, Nx, or any build system via the impacted-targets API" — the parallel-queues sub-page already documents the "Other" path; the old overview was excluding a real customer segment.

Audience targeting

This rewrite uses the skeptical-engineer overview pattern (committed locally; not yet shared). The marketing site does the selling; /getting-started/ does onboarding; this page does the "is this worth ten more minutes?" mental model. No customer names, no numeric outcome claims — mechanics + visuals are the only evidence.

Items flagged for review

  • Tile descriptions are tight on purpose. Mintlify Tiles truncate after a short visible line — descriptions are deliberately 20–25 chars. Open to making them even shorter or dropping description entirely.
  • Icons are boxes-stacked, columns-3, shield-check (FontAwesome / Lucide resolved by Mintlify). Easy to swap.
  • Direct merge to main is included in "More to dial in" based on the settings UI inventory. Not sure if it deserves a tile of its own — currently feels more like a niche optimization than a peer to the big three.
  • Tile fallback question — Tile component is new to docs2 (no other page uses it yet). Card is more common; if Tile renders weirdly on prod, swap is mechanical.

Test plan

  • Review on Mintlify preview when it builds
  • Check tile layout on narrow viewports (sidebar makes the available width tight)
  • Verify all linked sub-pages still exist (predictive-testing, priority-merging, direct-merge-to-main, etc.)
  • Eli does a sanity read against the original three complaints

🤖 Generated with Claude Code

@samgutentag samgutentag marked this pull request as ready for review May 22, 2026 06:11
@samgutentag
Copy link
Copy Markdown
Member Author

samgutentag commented May 26, 2026 •
edited
Loading

Verification status (2026-05-29): live

Verified: customers can use this. Ready to publish.

  • Flag state: no feature flag involved; LaunchDarkly not consulted (nothing to read)
  • Eng PR: none (content rewrite)
  • Flag: none
  • Signals: No engineering dependency and no feature flag. This is a ground-up rewrite of the Merge Queue overview page, replacing marketing-style claims with mechanic-first descriptions of existing shipped features (batching, parallel queues, anti-flake protection, predictive testing, direct merge to main, priority merging). All referenced features are already live and documented on sub-pages. Triggered by Eli feedback on 2026-05-21.

Ready to publish after editorial review.

Generated by Claude Code

@samgutentag samgutentag added the ready to merge Verify docs PR: customers can use this. Ready to publish. label May 26, 2026
samgutentag and others added 4 commits May 26, 2026 13:53
@samgutentag @claude
docs(merge-queue): rewrite overview for skeptical CI engineers
3ea5c75 
Replaces marketing-style "Big Three problems" framing with a
mechanics-first overview. Addresses Eli's feedback (2026-05-21):
- "Big three items don't make sense or are outright lies"
- "Calls out Nx/Bazel but not other build systems"
- "Not selling - no clear audience, layout sucks"

Page now:
- Opens with a 2-paragraph hook that introduces predictive testing
  as the baseline every queue does, then names the three Trunk-
  specific layers (batching, parallel queues, anti-flake protection).
- Gives each layer its own section with a plain-language mechanic
  explanation, the existing sub-page iframe, a one-line "what it
  costs you not to have it", and a link to the deep page.
- Replaces "Native Bazel/Nx" with framing that includes any build
  system via the impacted-targets API.
- Adds a "When does this make sense?" decision tree mapping symptom
  to mechanic in recognition voice.
- Drops unsupported claims: "Batch up to 100 PRs", "cut CI costs
  up to 90%", "Automatic quarantine of flaky tests" (which was the
  wrong product entirely).
- Strips marketing words per global style guide.

Pattern captured for reuse on other product overviews at
.claude/patterns/product-overview-for-skeptical-engineers.md
(in main worktree, untracked).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag @claude
docs(merge-queue): switch overview to Tiles layout
111c4db 
Replaces the three stacked mechanic sections with a 3-column
Tiles layout (boxes-stacked / columns-3 / shield-check icons +
title + short description) that links each tile to its deep page.

- Tighter at-a-glance preview of batching / parallel queues /
  anti-flake protection
- Adds Direct merge to main to "More to dial in" (the one
  architectural optimization in the settings UI that wasn't
  already represented at the top)

The Vidyard / iframely embeds drop off this page; they still
live on the deep optimization pages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag @claude
docs(merge-queue): drop "flake" from anti-flake tile description
bddd922 
The tile title is "Anti-flake protection" so "Flakes don't evict
PRs." was redundant. "CI gets a second chance." carries the same
intuition without the duplicated noun.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag @claude
docs(merge-queue): promote predictive testing to a 4th tile
5ec6e1a 
Adds Predictive testing as a peer tile alongside batching, parallel
queues, and anti-flake protection. Layout becomes 2x2.

Intro tightened to call out the actual relationship between the
mechanics: predictive testing is the correctness baseline; the other
three are throughput and resilience optimizations on top of it. The
old "three things on top of that baseline" wording overstated the
hierarchy - parallel queues is a separate design axis, not strictly
derived from predictive testing.

Crystal-ball icon for the predictive tile (small wink at "looking
ahead" without being too cute).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag samgutentag force-pushed the sam-gutentag/merge-queue-overview branch from 5a04f3a to 5ec6e1a Compare May 26, 2026 20:53
@samgutentag @claude
docs(merge-queue): lead overview with parallel queues, not batching
4b1c96c 
Eli flagged the description line ('batches PRs, bisects failures') for
leading with two batching-specific features when batching isn't the
primary winner. Reframe the page to lead with parallel queues — the
direct answer to GitHub MQ's single serial queue and the most-cited
real customer win — with anti-flake second and batching last.

- Description line now leads parallel queues > anti-flake > batching
- Tile grid reordered so batching moves out of the lead-differentiator
  slot (predictive baseline > parallel > anti-flake > batching)
- 'When does this make sense?' leads with the parallel-queues symptom

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented May 31, 2026

Verification status (May 31, 2026): live

Editorial rewrite of existing Merge Queue overview — no feature flag, no eng dependency.

  • Flag state: not consulted
  • Eng PR: none
  • Flag: none
  • Signals: documents existing, shipped behavior; no gating required

Next action: merge this PR.

Generated by Claude Code

@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented Jun 1, 2026

Docs Verify Sweep · June 1, 2026 · ✅ live

Feature is live in production. Ready to merge.

Unchanged from previous sweep (May 31, 2026).

Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

ready to merge Verify docs PR: customers can use this. Ready to publish.

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@samgutentag