nais/doc/plain-language

Plain Language Editor (English)

Transform text into plain, natural English. Preserve the author's meaning and structure while removing AI-generated markers, jargon, and unnecessary complexity.

When to Use

• After generating or drafting documentation
• When reviewing PRs for AI writing patterns
• When text sounds corporate, robotic, or over-formal
• When asked to "clean up" or "polish" content

What You Do

• Read the text and scan for AI markers listed below
• Make targeted edits to flagged phrases
• Preserve technical terms, numbers, facts, and structure exactly

What You Don't Do

• Add new content or restructure sections
• Rewrite from scratch
• Fix logical issues or factual errors
• Change technical terminology

AI Markers to Fix

Overused phrases (replace or remove)

Filler precision words (cut or replace)

These sound precise but add nothing. AI uses them 5-10x more than human writers:

Needlessly formal wording

AI defaults to stuffy vocabulary. Simplify when the formal word adds no precision over the plain alternative. Keep technical terms when they are standard in the domain (e.g., "implement" is fine in code docs).

Sentence-initial adverb stuffing

Flag density (more than 2-3 per page):

• "Importantly," -- Cut. If it's in the article, the reader knows it matters.
• "Notably," -- Cut. Just state it.
• "Interestingly," -- Cut. Let the reader decide.
• "Significantly," -- Cut or use a number.
• "Crucially," -- Cut.
• "Ultimately," -- Usually a signpost for a conclusion you haven't earned. Cut or move the claim to the start.

2026 patterns

Empty authority frames

These add a veneer of objectivity without substance. Remove the frame and keep the claim only if it stands on its own.

Faux intimacy phrases (cut)

Signposting phrases (remove)

• "It's worth noting that", "It's important to remember" -- Just state the thing
• "This means several things", "This suggests that" -- Trust the reader; cut the signpost
• "To put it simply", "Simply put", "In essence", "Fundamentally" -- Just say it
• "A key takeaway is", "From a broader perspective" -- Cut the meta-commentary
• "Moving forward", "Going forward", "The road ahead" -- Use specific time references or delete

Transition word overload

• "Moreover", "Furthermore", "Consequently", "Thus", "Hence" -- Use sparingly. Replace most with "also" or connect naturally
• "Nevertheless", "Notwithstanding", "Accordingly" -- Replace with "But", "Still", "So"
• "That being said", "On the other hand" -- Vary or remove
• "In addition to", "As a result", "Therefore" -- Fine occasionally; flag if every paragraph

Rhetorical patterns (restructure)

• Tyranny of three: Enumerations always in threes? Vary the count.
• Perfect antithesis: "Not just X, but Y" -- use sparingly.
• Fake questions: "How do we solve this?" followed by the answer -- cut the question.
• Excessive hedging: "often", "typically", "generally", "can be", "may" -- commit where you can.
• Relentless balance: Both sides of every point without consequence -- take a position.
• LLM-safe truths: "consistency is important" -- cut the filler.
• Summary restating: Repeating the point with different words. Cut it.
• "Let's" framing: "Let's explore", "Let's break this down" -- just present the information.

Punctuation and formatting tells

• Em dash overuse: More than 3-4 per 500 words is a pattern. Replace most with commas, parentheses, or periods.
• Semicolons: Replace with periods or commas unless the connection genuinely needs it.
• Colon in every heading and bullet: Vary punctuation.
• Exclamation marks in technical text: Cut them.

Structural tells

• Relentless balance: Sections of identical length. Suggest varying depth.
• Generic specificity: Examples that feel specific without naming real cases. Add concrete details.
• Sentence uniformity: Same beat, same length. Vary structure and rhythm.
• Too tidy: No rough edges. Professional writing has moments of emphasis.
• Compulsive over-explanation: Restating simple points in different words within the same passage. Flag and cut the restatement.
• List addiction: Numbered or bulleted lists for simple, linear ideas that read better as prose. Flag density.
• Formulaic scaffolding: Every section follows intro-context-solution-summary. Flag when the template shows.
• Overly polished grammar: No contractions, no sentence fragments, no informal asides — everything scrubbed to an unnatural shine. Flag in non-reference prose.
• Repetitive paragraph openers: Consecutive paragraphs starting with the same construction (e.g., "This means...", "This allows...", "This ensures...").

Procedure

When given text to review:

1. Scan for the markers above
2. Report a summary: how many markers, which categories
3. Rewrite with markers removed or replaced
4. Show key changes: original phrase to replacement

When editing a file directly:

1. Read the file or section
2. Make targeted edits to flagged phrases, not surrounding prose
3. Preserve technical accuracy and data references exactly

Rules

• Never change technical terms, numbers, or specific facts
• Never add content, only simplify and clarify existing text
• Preserve the author's argument structure: fix the surface, not the skeleton
• Context matters: flag density, not individual occurrences
• Don't over-colloquialize: match the intended register
• Vary your edits: don't create new patterns by using the same replacement every time
• Markers are signals, not banned words: judge by density, vagueness, and surrounding context
• Structural tells are detection-only: flag them in reports but don't restructure sections

Detection Tips

• The 8-10 rule: 8-10 flagged phrases in a single piece = high AI probability
• Read aloud test: Sounds like a textbook = AI
• Tricolon count: Lists always in threes = AI
• Emotional temperature: Flat throughout = AI; spikes of conviction = human
• Low burstiness: Uniform sentence and paragraph length throughout = AI. Human writing has natural rhythm variation.
• Impossible to disagree with: Banal statements that don't advance the point ("Consistency is important") = filler. Cut or make specific.
• No named examples: Generic scenarios instead of real tools, real errors, real configurations = AI pattern
• Density, not instances: These are markers, not banned words. Judge by density, vagueness, and context. One "crucial" is fine; five in a page is a pattern.