Overhaul docs tone guidance and rewrite platform overview as example - #606
Overhaul docs tone guidance and rewrite platform overview as example#606hongyi-chen wants to merge 4 commits into
Conversation
Expand the AGENTS.md Voice & tone section with concrete anti-AI-slop rules modeled on the GitHub and Vercel docs: define-show-link pattern, document the user-visible model (not internal architecture), words to avoid, structural patterns to avoid, and a stricter callout budget (never consecutive, at most one per section). Propagate the rules to the drafting/review workflow: - draft_docs: tone bullets in critical rules + checklist - review-docs-pr: tone/AI-ism review focus item - style_lint: report-only tone checks (tone-buzzword, tone-meta-opener, callout-consecutive, callout-density), never auto-fixed - oz-style-guidelines: align voice section; fix stale 'Ask Oz to...' preferred phrases from before the Automation Platform rename Rewrite platform/overview.mdx as the example page: user-visible model instead of orchestrator/control-plane internals, one callout instead of five, ~65% shorter. Fix the one anchor that pointed at the renamed section (environments.mdx: #execution-hosts -> #hosts). Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR was generated with Warp. Comment   |
|
Your GitHub account is not connected to Warp. Connect it here. |
The tone rewrite over-cut: trigger context, the Warp-vs-customer infrastructure diagram, API/SDK team use cases, the integration setup pointer, and cloud provider credentials had no equivalent on linked pages. Restore them in the new style. Details that live on dedicated pages (when to use environments, task states, CLI command reference) stay linked instead of restated. Co-Authored-By: Warp <agent@warp.dev>
warp-factory-examples #10 (plain-language pass) and #11 (follow-up trims from human review) surfaced patterns the tone section didn't cover yet: - Relocate, don't delete: detail in the wrong register (provenance, pinned versions, maintainer process) moves to the surface whose audience needs it, with a pointer, instead of being cut outright. - Say it once, across pages: shared boilerplate lives on the parent or reference page, not repeated on every sibling. - Keep the author out of it: no self-commentary, rules stated calmly without defensive emphasis, describe the present rather than weaving rename history through pages. - Slashed shorthand reads as notes, not prose. - Cut again: a plain-language rewrite under-cuts on the first pass; follow with a deletion-only pass. #11 existed because human review asked for more cutting after #10 had already landed. Also adds the second-pass and relocation items to the draft_docs checklist. Co-Authored-By: Warp <agent@warp.dev>
|
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 Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
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_linttone checks are wired into every scan without tests for the matching and exclusion behavior. Existing lint rules in this repository have focusedtest_*.pyregression 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
| issues.extend(check_screenshot_widths(lines, str(filepath))) | ||
| issues.extend(check_video_embed_titles(lines, str(filepath))) | ||
| issues.extend(check_callout_syntax(lines, str(filepath))) | ||
| issues.extend(check_tone_buzzwords(lines, str(filepath))) |
There was a problem hiding this comment.
style_lint rules have focused test_*.py coverage; add cases for buzzwords, meta-openers, inline/code-block skipping, consecutive callouts, and density before wiring these into run_all_checks.
| - Don't use corporate or disconnected language | ||
| - Skip theoretical posts without practical value | ||
| - Don't list features without context or problem-solving | ||
| - Don't use AI-slop buzzwords ("seamless," "powerful," "robust," "leverage," "streamline"): name the specific capability instead |
There was a problem hiding this comment.
I've been seeing a lot of compound sentences with both em-dashes and colons. These stylistic choices are okay but sparingly, and I'm seeing them in more than 50% of paragraphs on new docs. Maybe we could add a "don't" about overuse of colons/em-dashes, and preferring concise, direct sentences.
There was a problem hiding this comment.
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.mdL230: "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:
-
AGENTS.md's own quality checklist got nothing.draft_docsgained 4 tone/brevity items; theAGENTS.mdchecklist (L900-916) gained zero. That checklist is the authority this PR keeps pointing at, and the two have now diverged. -
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.)
-
4 per-type drafting skills have no tone/brevity mention:
draft_conceptual,draft_quickstart,draft_troubleshooting,draft_feature_doc.draft_quickstartis 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.
| # "harness" (agent harness), "unlock" (login/keychain unlock), "elevate(d)" | ||
| # (elevated permissions), and "journey" stay out of the lint and are covered | ||
| # by AGENTS.md only. | ||
| TONE_BUZZWORDS: List[Tuple[str, str]] = [ |
There was a problem hiding this comment.
The lint covers 2 of the 6 filler frames in AGENTS.md. Missing: designed to, ensures that, allows you to, in order to. Also missing landscape and realm from Abstract dramatics.
in order to → to and allows you to are the highest-frequency AI tells here and are trivially matchable.
The four intentional exclusions are documented in the comment above; these six just aren't here, which reads as oversight rather than judgment. Either add them or note why not.
| if in_code_block: | ||
| continue | ||
| prose = _strip_inline_code(line) | ||
| for pattern, suggestion in TONE_BUZZWORDS: |
There was a problem hiding this comment.
The three new checks ship without tests. style_lint/ already has test_factory_proper_noun.py, test_hardcoded_var_exemptions.py, and test_platform_determiner.py — and the SKILL.md edited in this PR says "Regression cases live in test_factory_proper_noun.py."
Regexes over prose are exactly where false positives creep in. A test_tone_checks.py with the intentional exclusions as negative cases would lock in the judgment calls you already made.
| 5. **Astro Starlight structure**: Verify `src/sidebar.ts` updates if files were added, moved, or renamed, and that redirects are added to the `redirects` array in `vercel.json` when needed. | ||
| 6. **Product name variables**: Check whether any product names with a corresponding entry in `src/data/vars.ts` are hardcoded as literal strings instead of using `{VARS.KEY}` (prose) or `{{TOKEN}}` (frontmatter). Key strings to watch for: "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run". Flag as `⚠️ [IMPORTANT]` if a new file adds these without using the variable system. For existing files, flag as `💡 [SUGGESTION]`. | ||
| 7. **AEO/source-data fit**: | ||
| 7. **Tone and AI-isms**: Flag marketing buzzwords (seamless, powerful, robust, comprehensive, leverage, streamline), meta-openers ("This page covers/explains/walks through..."), restated cause-and-effect ("This process ensures..."), recap lines, consecutive callouts or more than one callout per section, and internal-architecture detail the reader can't act on (orchestrators, control planes, lifecycle states). Reference the "Voice & tone" section of `AGENTS.md`. Use `💡 [SUGGESTION]` for isolated instances; use `⚠️ [IMPORTANT]` when the pattern is pervasive in new content. |
There was a problem hiding this comment.
This covers tone thoroughly but never mentions length or the "Cut again" deletion pass. The only adjacent word in the whole skill is "Scannability."
So a reviewing agent flags leverage and misses a 2,000-word page that should be 600 — the more expensive problem, and the one we're actually seeing.
Suggest adding length as its own item: flag pages that could be materially shorter, and check that a deletion pass happened.
2 participants
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:
.agents/rules/oz-style-guidelines.mdis aligned with the new rules and its stale pre-rename "Ask Oz to..." preferred phrases are fixed.2. Enforcement
draft_docsskill: tone bullets in the critical rules and the pre-publish checklist.review-docs-prskill: 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.mdxModeled on GitHub's "Understanding GitHub Actions": lead with what you can do, define each primitive in a few plain sentences, link out for depth.
environments.mdx:#execution-hosts→#hosts).Follow-ups (not in this PR)
platform/environments.mdx(9 callouts, a verbatim duplicated sentence) andplatform/integrations/github-actions.mdx("integrates seamlessly", consecutive callouts) are the next rewrite candidates.Validation
npm run buildpasses (376 pages).style_lintregression suites pass (11/11, 21/21); the rewritten overview passes the full lint with 0 issues; new tone checks verified to fire on known-bad pages.Plans: