docs/USER_GUIDE.md

# User Guide

## Getting Started

### Accessing the Application

Once deployed, access the Writing Studio through your web browser:
- Local: `http://localhost:7860`
- Production: `https://your-domain.com`

### Interface Overview

The application consists of several main sections:

1. **Input Section**: Where you paste your draft
2. **Configuration Section**: Model and prompt pack selection
3. **Results Section**: Original, revision, and feedback
4. **Diff View**: Visual comparison of changes

## Using Writing Studio

### Step 1: Paste Your Text

In the "Your Draft" text box, paste or type the text you want to analyze. This can be:
- An essay paragraph
- A complete essay
- A technical document section
- A creative writing piece
- Any text up to 10,000 characters

### Step 2: Select Model (Optional)

The default model `distilgpt2` works well for most cases. You can also try:
- `gpt2` - Larger, more sophisticated
- `gpt2-medium` - Even better quality, slower
- `gpt2-large` - Best quality, requires more resources

### Step 3: Choose Prompt Pack

Select the writing context that best matches your needs:

#### General
For everyday writing, emails, and general purpose text. Focuses on:
- Overall clarity
- Audience appropriateness
- Balanced tone

#### Literature
For literary analysis and critical essays. Emphasizes:
- Theme analysis
- Literary devices
- Textual evidence
- Academic tone

#### Tech Comm
For technical documentation and instructions. Optimizes for:
- Precision and accuracy
- Clear instructions
- Professional terminology
- Step-by-step clarity

#### Academic
For research papers and scholarly writing. Focuses on:
- Formal academic tone
- Logical organization
- Strong evidence and citations
- Objective language

#### Creative
For stories, poems, and creative pieces. Enhances:
- Descriptive language
- Voice and style
- Imagery and sensory details
- Narrative flow

### Step 4: Analyze & Compare

Click the "Analyze & Compare" button. The system will:
1. Validate your input
2. Load the selected model (if different)
3. Generate an AI revision
4. Score your text on rubric criteria
5. Create a visual diff

**Note**: First-time model loading may take 30-60 seconds. Subsequent analyses are much faster due to caching.

## Understanding the Results

### Original Draft
Your unchanged text, showing exactly what you submitted.

### AI Suggested Revision
The AI-generated improvement based on the selected prompt pack. This is a suggestion, not a requirement. Use your judgment!

### Rubric Feedback

The rubric analyzes your text on five criteria:

#### Clarity (1-5 points)
- **What it measures**: Sentence structure and comprehension
- **5 points**: Clear, well-structured sentences (15-20 words avg)
- **3 points**: Some complex or choppy sentences
- **1 point**: Very unclear or poorly structured

**How to improve**:
- Break up sentences over 25 words
- Combine sentences under 10 words
- Use active voice
- Define technical terms

#### Conciseness (1-5 points)
- **What it measures**: Wordiness and redundancy
- **5 points**: Direct language, no fluff
- **3 points**: Some wordy phrases
- **1 point**: Excessive wordiness

**How to improve**:
- Replace "in order to" with "to"
- Replace "due to the fact that" with "because"
- Remove unnecessary adverbs
- Use strong verbs instead of verb + adverb

#### Organization (1-5 points)
- **What it measures**: Structure and flow
- **5 points**: Clear paragraphs with transitions
- **3 points**: Some structure, needs transitions
- **1 point**: No clear organization

**How to improve**:
- Use paragraph breaks
- Add transition words (however, therefore, moreover)
- Start with topic sentences
- End with concluding sentences

#### Evidence/Support (1-5 points)
- **What it measures**: Use of examples and data
- **5 points**: Strong, specific evidence
- **3 points**: Some examples
- **1 point**: No evidence or support

**How to improve**:
- Add specific examples
- Include data or statistics
- Use phrases like "for example" or "research shows"
- Cite sources (when applicable)

#### Grammar (1-5 points)
- **What it measures**: Basic grammar and mechanics
- **5 points**: No obvious errors
- **3 points**: A few errors
- **1 point**: Many errors

**How to improve**:
- Check capitalization
- Review subject-verb agreement
- Proofread for typos
- Use grammar checking tools

### Highlighted Differences

The diff view shows:
- **Red/Pink**: Text removed or changed in revision
- **Green**: Text added or improved in revision
- **White**: Unchanged text

Use this to understand what changes the AI made and why.

## Tips for Best Results

### Writing Your Draft

1. **Be complete**: Submit full paragraphs or sections, not fragments
2. **Provide context**: The AI works better with complete thoughts
3. **Check length**: Longer texts take more time to process
4. **Start focused**: Begin with one paragraph, then expand

### Choosing Models

- **Start small**: Use `distilgpt2` initially
- **Upgrade gradually**: Try `gpt2` if you need better quality
- **Consider time**: Larger models are slower but produce better results
- **Cache benefit**: Using the same model for multiple analyses is faster

### Selecting Prompt Packs

- **Match your context**: Choose the pack that fits your writing situation
- **Experiment**: Try different packs to see different perspectives
- **Combine insights**: Use General first, then try specific packs

### Interpreting Results

1. **Use as guidance**: AI suggestions aren't always correct
2. **Learn patterns**: Notice what types of changes the AI makes
3. **Apply selectively**: Adopt improvements that make sense
4. **Maintain your voice**: Don't lose your personal style

## Advanced Features

### Caching

The system caches results to speed up repeated analyses:
- Same input + same settings = instant results
- Cache persists across sessions
- Clear cache to force new analysis

### Rate Limiting

To ensure fair usage:
- Default: 10 requests per minute
- Adjustable in configuration
- Helps prevent system overload

### Metrics and Monitoring

For administrators:
- Request counts and durations
- Error rates
- Cache hit rates
- System health

## Common Workflows

### Essay Writing Workflow

1. **Draft**: Write your first draft normally
2. **Analyze**: Submit to Writing Studio with "Academic" pack
3. **Review**: Check rubric scores and identify weak areas
4. **Revise**: Apply suggested improvements selectively
5. **Re-analyze**: Submit revised version to track improvement
6. **Finalize**: Polish based on feedback

### Technical Documentation Workflow

1. **Write**: Create initial technical content
2. **Check clarity**: Use "Tech Comm" pack
3. **Review feedback**: Focus on Clarity and Organization scores
4. **Simplify**: Apply conciseness suggestions
5. **Verify**: Ensure technical accuracy maintained

### Creative Writing Workflow

1. **Create**: Write your creative piece
2. **Enhance**: Use "Creative" pack for suggestions
3. **Compare**: Review diff for language improvements
4. **Balance**: Keep your voice while improving clarity
5. **Polish**: Final review with "General" pack

## Troubleshooting

### "Text exceeds maximum length"
- **Solution**: Break text into smaller sections
- **Limit**: 10,000 characters by default
- **Tip**: Analyze paragraph by paragraph

### "Model loading failed"
- **Cause**: Network issues or invalid model name
- **Solution**: Check model name spelling
- **Tip**: Use default models for reliability

### "Analysis is slow"
- **Cause**: Large model or first-time loading
- **Solution**: Use smaller models or wait for cache
- **Tip**: distilgpt2 is fastest

### Results seem incorrect
- **Cause**: Model limitations or prompt mismatch
- **Solution**: Try different prompt pack
- **Tip**: AI isn't perfect, use your judgment

## Privacy and Data

### What We Store
- Temporary: Analyzed texts during session
- Cached: Results for faster retrieval
- Logs: System operations (not text content)

### What We Don't Store
- Your original text (long-term)
- Personal information
- User profiles (unless auth enabled)

### Security
- All text is sanitized
- Input validation prevents attacks
- Rate limiting prevents abuse

## Keyboard Shortcuts

- `Ctrl/Cmd + Enter`: Submit analysis (when input focused)
- `Tab`: Navigate between fields
- `Ctrl/Cmd + A`: Select all text

## Best Practices

### Do's
✓ Submit complete thoughts and paragraphs
✓ Review all rubric categories
✓ Use suggestions as learning tools
✓ Try multiple prompt packs
✓ Keep your unique voice

### Don'ts
✗ Don't blindly accept all suggestions
✗ Don't submit incomplete fragments
✗ Don't expect perfect grammar detection
✗ Don't overuse the same model
✗ Don't rely solely on AI feedback

## Getting Help

- Check error messages for specific guidance
- Review rubric criteria explanations
- Experiment with different settings
- Consult documentation
- Report issues to administrators

## Educational Use

### For Students
- Use to improve drafts before submission
- Learn from rubric feedback
- Develop self-editing skills
- Track improvement over time

### For Teachers
- Use as teaching tool for revision
- Demonstrate different writing styles
- Show before/after comparisons
- Discuss AI limitations and strengths

### Classroom Activities
1. **Peer comparison**: Compare AI and peer feedback
2. **Rubric calibration**: Align student and AI scores
3. **Revision tracking**: Show iterative improvement
4. **Genre study**: Compare results across prompt packs