Document Review Skill

Objectives

Review technical documentation across 7 dimensions: Consistency, Accuracy, Clarity, Conciseness, Errors, Organization, and Content Relevance. Identify unnecessary content and provide actionable feedback with prioritized fixes.

Core Principle: 简单就是美 (Simplicity is Beauty)

• •Less is more: Remove everything that doesn't serve the core purpose
• •One concept, one explanation: No redundant content
• •Essential only: If readers can succeed without it, remove it

Review Dimensions

1. Consistency (一致性)

• •Terminology: Same concepts use same terms throughout
• •Formatting: Uniform heading levels, code blocks, lists
• •Naming: Variable/function names match actual code
• •Notation: Mathematical symbols used consistently (e.g., γ always for gamma)

2. Accuracy (准确性)

• •Technical Facts: Formulas, algorithms, concepts are correct
• •Code Correctness: Snippets match actual implementation
• •References: Links, file paths exist and are valid
• •Examples: Produce stated outputs

3. Clarity (理解性)

• •Explanations: Complex concepts broken down clearly
• •Examples: Abstract ideas paired with concrete examples
• •Flow: Logical progression from simple to complex
• •Jargon: Technical terms explained when first introduced

4. Conciseness (精简度)

• •Redundancy: No unnecessary repetition
• •Relevance: All content serves a purpose
• •Efficiency: Key points easy to find

5. Errors (错误检测)

• •Spelling/Grammar: No typos or grammatical errors
• •Syntax: Markdown renders properly
• •Broken Elements: Dead links, missing images, broken code blocks

6. Organization (组织结构)

• •Hierarchy: Clear section organization
• •Navigation: TOC present, headings logical
• •Grouping: Related content together
• •Flow: Prerequisites before advanced topics

7. Content Relevance (内容相关性) 🆕

• •Core vs Peripheral: Distinguish essential content from nice-to-have
• •Redundancy Detection: Identify duplicate explanations across sections
• •Scope Alignment: Flag content beyond document's stated objectives
• •Unused Concepts: Identify explained concepts never applied in practice
• •Bloat Indicators: Multiple tables/examples explaining same concept

Content Pruning Guidelines

Philosophy: 简单就是美 (Simplicity is Beauty)

When identifying unnecessary content, ask: "Can readers succeed without this?" If yes, remove it.

1. •

   Duplicate Explanations: Same concept explained in multiple sections

   • •Keep the best explanation, reference it elsewhere
   • •Example: Bellman equation explained in both Part 3 and Part 4
   • •Principle: One concept = One explanation
2. •

   Unused Theory: Concepts explained but never used in practice

   • •Example: Transition probability P(s'|s,a) in deterministic environment
   • •Action: Remove or move to "Advanced Topics" appendix
   • •Principle: If not used, not needed
3. •

   Excessive Tables: Multiple tables showing similar information

   • •Keep the clearest one, remove redundant tables
   • •Example: Three different comparison tables in introduction
   • •Principle: One table is better than three
4. •

   Over-detailed Symbols: Symbol tables with unused notation

   • •Only include symbols actually used in the document
   • •Example: General math symbols (Σ, ∞) when not used
   • •Principle: Essential symbols only
5. •

   Scope Creep: Advanced topics beyond document's learning objectives

   • •Example: Deep Q-Networks in a basic Q-Learning tutorial
   • •Action: Move to separate "Further Reading" document
   • •Principle: Stay focused on core objectives
6. •

   Verbose Examples: Too many examples for simple concepts

   • •One clear example is usually enough
   • •Multiple examples only for complex/critical concepts
   • •Principle: Quality over quantity
7. •

   Backup Files: Keep only the final, best version

   • •Delete verbose backups, drafts, and alternative versions
   • •Principle: 简单就是美 - One clean version is enough

Review Process

1. •Initial Scan: Read title, TOC, skim headings to understand structure and objectives
2. •Systematic Review: Go through each dimension checking against criteria
3. •Content Relevance Check: Identify sections that don't serve core objectives
4. •Generate Report: Use output format below with pruning recommendations

Output Format

# Document Review Report

**Document**: [filename]
**Reviewed**: [date]

## Summary

[1-2 sentence overall assessment]

## Strengths ✅

- [What works well - 3-5 points]

## Issues Found 🔍

### Critical Issues ⚠️

1. **[Dimension]**: [Issue with location]
   - **Impact**: [Why this matters]
   - **Fix**: [How to resolve]

### Major Issues ⚡

1. **[Dimension]**: [Issue]
   - **Fix**: [Recommendation]

### Minor Issues 📝

1. **[Dimension]**: [Issue]
   - **Fix**: [Quick fix]

## Priority Fixes (Top 3)

1. [Most important fix]
2. [Second priority]
3. [Third priority]

## Content Pruning Recommendations 🆕

### High Priority Removal (Redundant/Unused)

1. **[Section]**: [What to remove]
   - **Reason**: [Why it's unnecessary]
   - **Impact**: [How much shorter document becomes]

### Medium Priority Simplification

1. **[Section]**: [What to simplify]
   - **Current**: [Current state]
   - **Suggested**: [Simplified version]

### Optional Content (Move to Appendix)

1. **[Section]**: [Advanced/tangential content]
   - **Reason**: [Why it's optional]
   - **Suggestion**: [Where to move it]

## Detailed Findings by Dimension

[Specific findings for each dimension including Content Relevance]

Key Instructions

1. •Be Specific: Point to exact locations (line numbers, section names)
2. •Be Constructive: Suggest improvements, not just criticisms
3. •Prioritize: Focus on high-impact fixes first
4. •Verify Code: Check that code snippets match actual implementation files
5. •Test Links: Verify all file paths and URLs are valid
6. •Check Consistency: Ensure terminology matches between code and docs
7. •Identify Bloat: Flag redundant, unused, or out-of-scope content
8. •Suggest Pruning: Provide specific sections to remove or simplify
9. •Embrace Simplicity: 简单就是美 - Always prefer the simpler, clearer version

Common Issues & Quick Fixes

Pruning Decision Framework

Use this framework to decide if content should be removed:

Is this content...
├─ Used in practice/code?
│  ├─ NO → Consider removing
│  └─ YES → Keep
├─ Explained elsewhere?
│  ├─ YES → Remove duplicate, add reference
│  └─ NO → Keep
├─ Within document scope?
│  ├─ NO → Move to appendix or separate doc
│  └─ YES → Keep
└─ Essential for understanding?
   ├─ NO → Consider removing
   └─ YES → Keep but simplify if verbose

Validation

Before finalizing review:

• • All issues have specific locations
• • Fixes are actionable and clear
• • Priority ranking makes sense
• • Strengths are acknowledged
• • Report is concise and scannable
• • Pruning recommendations are justified
• • Estimated length reduction calculated
• • Final version embraces 简单就是美 (simplicity is beauty)

Simplicity Checklist

After pruning, verify the document follows these principles:

• • One Purpose: Document has a clear, single objective
• • One Explanation: Each concept explained once, referenced elsewhere
• • Essential Only: Every section serves the core purpose
• • No Redundancy: No duplicate tables, examples, or explanations
• • Clean Structure: Clear hierarchy, easy navigation
• • Minimal Versions: Only one final version, no backups in repo

Remember: 简单就是美 - If readers can succeed without it, remove it.

For detailed review guidelines and examples: See references/review-guide.md (if needed)