writing-style

name: writing-style description: Economist-inspired writing principles for marvinzhang.dev. Covers the five pillars (clarity, precision, active voice, concrete examples, data-driven), tone and voice guidelines, sentence variety, word choice hierarchy, and structural excellence. Load this skill for writing, editing, or style review. metadata: author: marvinzhang version: "2.0" tier: foundation

Writing Style (Economist-Inspired)

Writing principles and voice guidelines for marvinzhang.dev.

Five Core Principles

1. Clarity:

• Lead with core idea in first paragraph
• One idea per sentence
• Define technical terms at first use
• Break up text density with subheadings and lists

2. Precision:

• Use specific numbers and measurements
• Name technologies with versions
• Time-stamp all claims
• Cut weasel words ("very," "quite," "rather")

3. Active Voice:

• "React renders" not "Components are rendered"
• "The API returns JSON" not "JSON is returned"
• Aim for 80%+ active voice
• Passive acceptable when actor is unknown or irrelevant

4. Concrete Examples:

• Real-world scenarios over abstract theory
• Familiar analogies for complex concepts
• Actual measurements and benchmarks
• Visual aids (diagrams, tables, flowcharts)

5. Data-Driven:

• Back claims with evidence
• Include statistics and measurements
• Link to primary sources (official docs, research papers)
• Show trade-offs honestly

Tone & Voice

• Professional yet accessible: Expert knowledge without condescension
• Conversational: Use "you" and rhetorical questions
• Authoritative but humble: Share expertise while encouraging learning
• Encouraging: Growth mindset emphasis

Avoid

• Condescension toward beginners
• Hype or marketing language
• Unnecessary complexity
• Unsubstantiated claims

Sentence Variety

Mix sentence lengths for rhythm:

• Short: Punch. Emphasis. Drama.
• Medium: Standard informational delivery.
• Long: When showing relationships between concepts.

Word Choice

Prefer:

1. Anglo-Saxon roots: "use" not "utilize," "buy" not "purchase"
2. Concrete nouns: "developers" not "stakeholders"
3. Strong verbs: "decide" not "make a decision"
4. Simple words: "help" not "facilitate," "show" not "demonstrate"

Cut Ruthlessly

When you think you're done, cut 10% more:

• ❌ Throat-clearing: "It should be noted that..."
• ❌ Redundancy: "Future plans," "past history"
• ❌ Qualifier bloat: "very," "really," "quite," "rather"
• ❌ Unnecessary phrases: "In order to" → "To"

References

• references/economist-principles.md — Detailed style guide with wit, structure, and craft guidelines