Overhaul docs tone guidance and rewrite platform overview as example

[hongyi-chen]

What this does

Makes the docs sound like they were written by a person, using the GitHub and Vercel docs as the reference tone. Three parts: expanded tone guidance, enforcement in the drafting/review/lint workflow, and one example page rewritten to demonstrate the target.

1. Tone guidance (AGENTS.md)

The Voice & tone section grows from 5 bullets to a full set of rules with before/after examples pulled from our own pages:

• Define, show, link - introduce a concept in 1-3 plain sentences, give an example, link out (the GitHub Actions docs pattern).
• Document the user-visible model, not our architecture - GitHub Actions runs on an orchestrator and a control plane; its docs never mention either. Ours shouldn't either.
• Every sentence earns its place - no meta-openers ("This page covers..."), no restated cause-and-effect, no recap lines, no repeated caveats.
• Words to avoid - seamless, powerful, robust, comprehensive, leverage, streamline, delve, "it's important to note", and friends.
• Structural patterns to avoid - rule-of-three padding, rhetorical question openers, hedging stacks, bold-everything, bullets-as-prose.
• Stricter callout budget - never consecutive, at most one per section (was "5+ loses impact").

.agents/rules/oz-style-guidelines.md is aligned with the new rules and its stale pre-rename "Ask Oz to..." preferred phrases are fixed.

2. Enforcement

• draft_docs skill: tone bullets in the critical rules and the pre-publish checklist.
• review-docs-pr skill: a tone/AI-ism review focus item.
• style_lint: four report-only checks, never auto-fixed: tone-buzzword, tone-meta-opener, callout-consecutive, callout-density. Words with legitimate uses here (harness, unlock, elevated, journey) are deliberately excluded from the lint. Current baseline across the docs: ~27 pages with buzzwords, 43 meta-openers.

3. Example rewrite: platform/overview.mdx

Modeled on GitHub's "Understanding GitHub Actions": lead with what you can do, define each primitive in a few plain sentences, link out for depth.

• 308 lines → 80 lines (~65% shorter); 5 callouts → 1 (the time-boxed rename notice).
• The "Warp Orchestrator" / "cloud control plane" / lifecycle-state internals collapse into user-visible behavior ("Warp tracks every run as a task...").
• Cut: "Key concepts" glossary dump, "In practice:" recap, "The sections below describe...", duplicated when-to-use lists that belong on child pages.
• Fixed the one inbound anchor that pointed at a renamed section (environments.mdx: #execution-hosts → #hosts).

Follow-ups (not in this PR)

• platform/environments.mdx (9 callouts, a verbatim duplicated sentence) and platform/integrations/github-actions.mdx ("integrates seamlessly", consecutive callouts) are the next rewrite candidates.
• A batch pass over the remaining ~27 buzzword-affected pages once this guidance lands.

Rework changes

Addressed Rachael's review comments and did a broader polish pass on the same diff:

• Reply-then-resolve on all 5 review threads (4 from Rachael, 1 from the automated review): resolved after posting a substantive reply on each.
• style_lint: added the 4 missing filler frames (designed to, ensures that, allows you to, in order to) and 2 missing abstract-dramatics words (landscape, realm) to the tone-buzzword check, plus a new test_tone_checks.py regression suite covering all three previously-untested tone checks (tone-buzzword, tone-meta-opener, callout-density/callout-consecutive).
• oz-style-guidelines.md: added a Don't against stacking an em dash and a colon in the same sentence.
• review-docs-pr: added a length/brevity review item so a reviewing agent flags an oversized page, not just isolated buzzwords.
• AGENTS.md: fixed the page-length guidance to "cut first, split only if it's still long" (previously contradicted the new tone guidance by telling authors to split first), and synced the canonical Quality checklist with the tone/brevity items draft_docs already carries.
• Extended brevity guidance to the rest of the drafting surface: added an explicit "delete any section you don't need" instruction to the 7 page templates that lacked one, and a tone/brevity rule to draft_conceptual, draft_quickstart (explicit ~600-word budget), draft_troubleshooting, and draft_feature_doc.
• Merge-conflict note (PR docs: gate the new feature docs pipeline on worthiness and trigger it from releases #586): acknowledged; docs: gate the new feature docs pipeline on worthiness and trigger it from releases #586 is still open/unmerged, so nothing to reconcile yet.
• Visual verification (rework cycle 1): captured computer-use screenshots of the rendered /platform/overview/ page (top: H1, opening paragraph, Note callout; bottom: Secrets/Shared configuration/Warp Factories/Where to go next) confirming the rewrite renders cleanly with no layout or content issues. See the screenshot block below and the linked ticket comment.

Validation

• npm run build passes (376 pages).
• style_lint regression suites pass (11/11 platform-determiner, 21/21 factory-proper-noun, 6/6 hardcoded-var-exemptions, 23/23 tone-checks); the rewritten overview passes the full lint with 0 issues; new tone checks verified to fire on known-bad pages.
• Internal link checker: 0 broken links.

Computer-use screenshots (2)

Top of the /platform/overview/ page showing the H1 "Automation Platform overview", opening paragraph, and a blue Note callout box about "Oz is now the Automation Platform"

Bottom of the /platform/overview/ page showing Secrets, Shared configuration, Warp Factories, and Where to go next sections with a bullet list of links, plus the page footer navigation

_Plans_: - _[Docs tone overhaul: human-sounding guidance + example rewrite](https://staging.warp.dev/drive/notebook/DO1CATrtUhGq1JiBCCNGMr)_

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 23, 2026 8:29pm

[hongyi-chen]

This PR was generated with Warp.

Comment @warp-agent on this PR to send it follow-up work.

 

[warp-factories]

Your GitHub account is not connected to Warp. Connect it here.

[warp-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR expands the docs tone guidance, adds report-only tone checks to style_lint, and rewrites the Automation Platform overview as an example of the new style. The content changes are generally coherent, and I did not find security issues or spec drift, but the new lint behavior is enabled without durable regression coverage.

Concerns

• The new style_lint tone checks are wired into every scan without tests for the matching and exclusion behavior. Existing lint rules in this repository have focused test_*.py regression scripts, and these regex-heavy checks need the same coverage before they start affecting docs review automation.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[rachaelrenk]

I think these changes are really valuable! A couple of things we might add, all on the brevity side.

Every new rule targets words and sentences. Nothing targets page length, which would be a useful thing to check against.

The section that owns length is untouched and prescribes the opposite remedy:

AGENTS.md L230: "If a page exceeds ~1500 words, consider breaking it into sub-pages or using clear anchor links."

Splitting a bloated page gives you two bloated pages. Suggest: cut first, split only if it's still long, with a pointer to "Cut again."

Some other thoughts:

1. AGENTS.md's own quality checklist got nothing. draft_docs gained 4 tone/brevity items; the AGENTS.md checklist (L900-916) gained zero. That checklist is the authority this PR keeps pointing at, and the two have now diverged.

2. 7 of 8 page templates carry no brevity guidance. Templates are where drafting starts, and one listing sections invites filling every one. Worth an explicit "delete any section you don't need; a short page is a finished page." (Also true of my template rewrite in #586 — shared gap, not yours.)

3. 4 per-type drafting skills have no tone/brevity mention: draft_conceptual, draft_quickstart, draft_troubleshooting, draft_feature_doc. draft_quickstart is the sharpest miss — quickstarts have a hard ~600-word budget and it's the one type where length is the constraint.

Note for posterity: there's a small conflict with #586.

CONFLICT (content): Merge conflict in .agents/skills/draft_docs/SKILL.md

Both PRs add bullets to the same "Critical formatting rules" list and the same checklist. AGENTS.md merges clean. Small, but shouldn't be auto-resolved — both sets should survive.

[warp-agent-staging]

Thanks for the review — addressed the inline comments individually (see replies on each thread). Responding here to the broader points in your review summary, in the same order:

1. Page length untouched / L230 contradiction. Fixed. The "Page length and scannability" section now says "cut first, split only if it's still long," points at the new "Cut again" section, and explicitly calls out that splitting a bloated page produces two bloated pages. (AGENTS.md, "Page length and scannability")

2. AGENTS.md's own checklist got nothing. Fixed. Added the same three items draft_docs' checklist already carries (tone rules, callout sparsity, the "Cut again" deletion pass) to the canonical Quality checklist in AGENTS.md so the two no longer diverge.

3. 7 of 8 templates carry no brevity guidance. Fixed. Added an explicit [BREVITY: Delete any section below you don't need — a short page is a finished page.] instruction to conceptual, procedural, reference, troubleshooting, FAQ, guide-page, and feature-doc templates (quickstart already had brevity language).

4. 4 drafting skills have no tone/brevity mention. Fixed draft_conceptual, draft_quickstart, draft_troubleshooting, and draft_feature_doc. draft_quickstart calls out the ~600-word budget explicitly, as you flagged as the sharpest miss.

5. Merge conflict note with docs: gate the new feature docs pipeline on worthiness and trigger it from releases #586. Noted, but docs: gate the new feature docs pipeline on worthiness and trigger it from releases #586 is still open/unmerged as of this branch's latest push, so there's nothing to reconcile yet — flagging for whoever merges second to make sure both sets of draft_docs bullets survive the conflict resolution.

Also did a general polish pass while in here: expanded the tone-buzzword lint list (the four missing filler frames plus landscape/realm) and added test_tone_checks.py regression coverage for the three previously-untested tone checks, addressing the other inline comments and the automated review's IMPORTANT finding. npm run build and all style_lint regression suites pass. Pushed in d91bfc8.

[warp-agent-staging]

Overview

Confirmed Rachael's review comments, the tone and brevity polish pass, and the refreshed visual verification for the rewritten platform overview.

Verdict

Checks: CI ✅ · build ✅ · style-lint suites ✅ · internal links ✅ · visual proof ✅
Found: 0 critical, 0 important, 0 suggestions

Approve

Review run

https://oz.staging.warp.dev/runs/01a0303a-2b51-7324-b052-a5e9ca654760