rewrite-doc

name

rewrite-doc

description

Rewrite documentation with localization-aware style for a specified audience. MUST use when the user mentions any of these actions on a document: 重写/改写/润色/本土化/翻译/转写/rewrite/rephrase/localize/translate/polish/adapt. Also trigger when user says "写成中文/英文", "用中文重新写", "make this more natural", "这个文档读起来像翻译", "帮我改成面向XX的", or provides a doc asking for better wording, tone adjustment, or audience adaptation. Covers: markdown docs, specs, READMEs, design docs, product docs, guides, changelogs.

Rewrite Doc

Rewrite documentation for a target audience while preserving technical precision.

When to Use

• User asks to rewrite, localize, or rephrase a document
• User provides a doc and specifies an audience or language preference
• User says the doc "reads like a translation" or needs better flow

Workflow

1. Identify Parameters

Before rewriting, determine:

Parameter	How to resolve
Output language	User-specified > auto-detect from user's input language
Audience	Ask if not obvious (e.g., senior engineers, junior devs, PMs, end users)
Register	Technical docs default to formal-concise; READMEs default to approachable

If the user doesn't specify language, match the language they're writing in.

2. Rewriting Principles

Structure:

• Headings use domain terminology in the lingua franca of the field (usually English for tech). This makes headings scannable and grep-friendly.
• Body text uses the target language natively, not translated. Write as a native speaker of that language would write for peers.

Terminology:

• Preserve technical terms in their canonical form (OKLCH, shadcn, RBAC, SSR, monorepo, CRUD, etc.)
• Do not translate proper nouns, library names, CLI commands, or code identifiers
• When a term has both a native word and an English loanword equally understood by the audience, prefer the one that reads more naturally in context

Tone calibration by audience:

Audience	Characteristics
Senior engineers	Dense, assumes context, no hand-holding. Skip obvious explanations.
Junior engineers	More connective tissue, brief clarifications for non-obvious concepts.
PMs / non-technical	Explain the "what" and "why", skip the "how" implementation details.
End users	Task-oriented, no jargon, action-first.

Anti-patterns to eliminate:

• Machine-translation artifacts ("进行操作" → just use the verb directly)
• Unnecessary filler ("需要注意的是", "值得一提的是")
• Passive voice where active is more direct
• Restating what the heading already says in the first sentence
• Em dashes (use commas, colons, semicolons, or parentheses instead)

3. Execute

1. Read the source document in full
2. Identify sections that are purely structural (tables, code blocks, YAML) vs. prose
3. Rewrite prose sections applying the principles above
4. Preserve code blocks, YAML frontmatter, and table data verbatim (only rewrite human-readable labels/descriptions within them)
5. Output the complete rewritten document

4. Self-check

After rewriting, verify:

• No heading is a literal translation of a Chinese/English phrase when the domain term exists
• No sentence starts with the same word as the heading above it
• Technical terms are consistent throughout (don't alternate between translations)
• The document flows naturally when read aloud in the target language