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