Making Files Clearer

A systematic approach to transforming verbose, redundant, or disorganized files into clear, concise, essential-only content.

Core Principles

1. Ruthless Elimination

• Remove redundancy: Delete duplicate information, repeated explanations, and overlapping content
• Cut fluff: Eliminate unnecessary adjectives, hedging language, and verbose phrasing
• Strip decorative elements: Remove ASCII art, excessive formatting, and visual noise unless they serve a functional purpose

2. Essential Information Only

• Keep what matters: Retain only information that directly serves the file's purpose
• Question every line: Ask "Does removing this change understanding?" If no, remove it
• Preserve accuracy: Never sacrifice correctness for brevity

3. Strategic Examples

• Examples add clarity when:
  • Concept is abstract or counterintuitive
  • Multiple valid interpretations exist
  • Common mistakes need illustration
• Examples are unnecessary when:
  • Concept is self-evident
  • They merely repeat what's already clear
  • They're "nice to have" but not essential

4. Logical Organization

• Group related content: Cluster similar topics together
• Progressive structure: Simple concepts before complex ones
• Clear hierarchy: Use headings to show relationships
• Scannable format: Readers should find information quickly

Workflow

Step 1: Create Backup

cp original.md original.md.backup

Step 2: Analyze Current State

1. Read the entire file
2. Identify the file's core purpose
3. List essential information categories
4. Note redundant sections, fluff, and organizational issues

Step 3: Create Clarity Plan

Before editing, outline:

• What to keep (essential information)
• What to remove (redundancy, fluff)
• How to reorganize (new structure)
• Where examples add value

Step 4: Execute Transformation

Apply changes systematically:

1. Remove: Delete redundant and unnecessary content
2. Reorganize: Restructure for logical flow
3. Clarify: Rewrite unclear sections concisely
4. Validate: Ensure no essential information lost

Step 5: Present Changes for Review

Show the user:

• Summary of what changed
• Before/after comparison
• Ask for confirmation

Step 6: Finalize

After user confirms:

rm original.md.backup

If user rejects changes:

mv original.md.backup original.md

Common Clarity Anti-Patterns

Redundancy

❌ Bad: Explaining the same concept multiple times in different words ✅ Good: One clear explanation, possibly with a targeted example

Unnecessary Examples

❌ Bad: "For instance, if you have a variable x = 5, that's an example of setting a variable" ✅ Good: "Variables store values: x = 5"

Verbose Phrasing

❌ Bad: "It is important to note that you should always make sure to..." ✅ Good: "Always..."

Over-Documentation

❌ Bad: Documenting every obvious step ✅ Good: Documenting non-obvious behavior and gotchas

Poor Organization

❌ Bad: Random topic ordering, nested sections with unclear purpose ✅ Good: Logical grouping, clear hierarchy, scannable headings

Output Format

When making a file clearer:

1. Show before/after comparison (if file is small enough):

   Original: 250 lines, 15 sections, 30% redundancy
   Revised: 120 lines, 8 sections, focused content
   

2. Summarize changes:

   • What was removed and why
   • How content was reorganized
   • Where examples were added/removed

3. Present the clarified content: Use Edit tool to update the file

4. Validate: Confirm all essential information preserved

Edge Cases

• Technical documentation: Preserve all technical accuracy; brevity should never compromise correctness
• Legal/compliance files: Consult before removing anything that might be required
• Tutorials: Examples are often essential; keep those that teach, remove those that just show off
• Configuration files: Comments may seem verbose but often prevent errors; keep contextual comments

Success Criteria

A file is clearer when:

• A first-time reader understands it faster
• Information is findable without scrolling/searching extensively
• No questions arise from ambiguity or missing context
• The file can be maintained more easily
• Essential information density is maximized