Spaces:
Sleeping
Sleeping
| # 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 | |