菜单
Simplification and readability techniques. Use when writing for broad audiences or simplifying complex content. Covers active voice, short sentences, jargon elimination, and accessibility principles from the Plain Language Movement.
| name | plain-language |
| description | Simplification and readability techniques. Use when writing for broad audiences or simplifying complex content. Covers active voice, short sentences, jargon elimination, and accessibility principles from the Plain Language Movement. |
Purpose: Write clearly and directly using active voice, simple sentences, and minimal jargon.
Origin: Plain Writing Act of 2010 (US), Plain Language Movement
Use When: Drafting and reviewing content to maximize clarity (Phases 4-5)
Plain language means readers understand immediately what you're saying - no rereading required.
Passive: Subject receives action ("The error was caught by the test") Active: Subject performs action ("The test caught the error")
Why Active is Better:
Examples:
❌ PASSIVE:
"The bug was discovered by the QA team"
"Performance improvements were made to the API"
"A decision will be made by the committee"
✅ ACTIVE:
"The QA team discovered the bug"
"We improved API performance"
"The committee will decide"
Detection Pattern: "was/were/is/are + past participle + by"
When Passive is Okay:
Principle: Long sentences increase cognitive load and reduce comprehension.
Targets:
Techniques:
❌ LONG (42 words):
"After extensive research and consideration of multiple
frameworks over several months using various criteria
including performance, ecosystem size, learning curve,
and community support, we determined that React offers
the best balance for our team's needs."
✅ SPLIT (2 sentences, 23 + 14 words):
"Our evaluation of 5 frameworks over 3 months ranked
React highest across 12 criteria, including performance,
ecosystem, and learning curve. React offers the best
balance for our team's needs."
How to Shorten:
Jargon: Specialized terminology that excludes readers.
When to Use Jargon:
When to Avoid:
Examples:
❌ JARGON HEAVY:
"Leverage microservices to achieve scalable, cloud-native
architecture with seamless integration paradigms"
✅ PLAIN:
"Break your application into small, independent services
that can scale individually and run in the cloud"
✅ JARGON EXPLAINED:
"Use microservices—small, independent services that handle
specific functions—to scale your application efficiently"
Nominalization (verb → noun weakens writing):
❌ make a decision → ✅ decide
❌ perform an analysis → ✅ analyze
❌ give consideration to → ✅ consider
❌ have a discussion about → ✅ discuss
Weak Verbs (vague actions):
❌ utilize → ✅ use
❌ facilitate → ✅ enable / allow
❌ implement → ✅ build / create
❌ leverage → ✅ use / apply
Redundancy (unnecessary words):
❌ advance planning → ✅ planning
❌ past history → ✅ history
❌ completely eliminate → ✅ eliminate
❌ end result → ✅ result
Weasel Words (often removable):
❌ very important → ✅ critical / important
❌ really significant → ✅ significant
❌ actually improves → ✅ improves
❌ basically works → ✅ works
Calculation:
Targets:
Calculation:
Targets:
30 words: Consider splitting
Plain language typically scores:
Plain language compliance:
Initialize Claude Code framework infrastructure for any project
Hierarchical content structure - answer first, then supporting arguments, then details
Narrative structure for complex topics - Situation, Complication, Question, Answer
Shared configuration patterns for project setup commands. Provides security hooks, Claude framework structure templates, and framework detection patterns used across multiple setup commands.
API authentication patterns including JWT, OAuth 2.0, API keys, and session-based auth. Covers token generation, validation, refresh strategies, security best practices, and when to use each pattern. Use when implementing API authentication, choosing auth strategy, securing endpoints, or debugging auth issues. Prevents common vulnerabilities like token theft, replay attacks, and insecure storage.
Docker image optimization patterns including multi-stage builds, layer caching, security hardening, and size reduction techniques. Use when building Docker images, optimizing container size, improving build performance, or implementing Docker security best practices. Reduces image sizes by 70-90% and build times by 50-80%.