swadhin / opengrammar public

swadhinbiswas

[email protected]
2026-03-14 19:13:59 +0600 committed NaN years ago
344c2a7
commit 344c2a7
1 file changed
+725 -0
Showing 1 changed file+725-0
docs/09-using-opengrammar.md
▼docs/09-using-opengrammar.md
+725-0
@@ -0,0 +1,725 @@
1
+# 📖 Using OpenGrammar - Complete User Guide
2
+
3
+Master OpenGrammar with this comprehensive guide to all features and functionality.
4
+
5
+---
6
+
7
+## 📋 Table of Contents
8
+
9
+1. [Getting Started](#getting-started)
10
+2. [Grammar Checking](#grammar-checking)
11
+3. [Tone Rewriting](#tone-rewriting)
12
+4. [Writing Statistics](#writing-statistics)
13
+5. [Custom Dictionary](#custom-dictionary)
14
+6. [Site-Specific Settings](#site-specific-settings)
15
+7. [Keyboard Shortcuts](#keyboard-shortcuts)
16
+8. [Tips & Best Practices](#tips--best-practices)
17
+
18
+---
19
+
20
+## 🚀 Getting Started
21
+
22
+### First Time Setup
23
+
24
+1. **Install the Extension**
25
+ - See [Browser Extension Setup](04-browser-extension-setup.md)
26
+
27
+2. **Configure Backend**
28
+ - Click extension icon → Settings
29
+ - Enter Backend URL (local or deployed)
30
+
31
+3. **Set Up AI Provider**
32
+ - Choose provider (Groq recommended for free tier)
33
+ - Enter API key
34
+ - Select model
35
+
36
+4. **Test It Out**
37
+ - Open any text box
38
+ - Type: `me and him went to store`
39
+ - You should see red underline
40
+
41
+---
42
+
43
+## ✍️ Grammar Checking
44
+
45
+### How It Works
46
+
47
+OpenGrammar uses a **dual-engine approach**:
48
+
49
+1. **Rule-Based Engine** (Free, Offline)
50
+ - 40+ grammar rules
51
+ - Instant checking
52
+ - No API required
53
+
54
+2. **AI-Powered Engine** (Advanced)
55
+ - Context understanding
56
+ - Complex grammar
57
+ - Requires API key
58
+
59
+### Color-Coded Underlines
60
+
61
+| Color | Meaning | Example |
62
+|-------|---------|---------|
63
+| **Red** | Spelling/Grammar | "teh" → "the" |
64
+| **Amber** | Clarity | Long sentences |
65
+| **Blue** | Style | Passive voice |
66
+
67
+### Using Grammar Checking
68
+
69
+#### Step 1: Start Typing
70
+Open any text input:
71
+- Gmail compose
72
+- Google Docs
73
+- Notion
74
+- Any text box on the web
75
+
76
+#### Step 2: Watch for Underlines
77
+As you type, OpenGrammar automatically checks:
78
+- After you stop typing (800ms delay)
79
+- Only text with 5+ characters
80
+- Works in real-time
81
+
82
+#### Step 3: Review Suggestions
83
+Click any underlined text to see:
84
+```
85
+┌─────────────────────────────┐
86
+│ 🔴 Grammar Error │
87
+│ │
88
+│ Original: me and him │
89
+│ Suggestion: he and I │
90
+│ │
91
+│ Subject pronoun error. │
92
+│ Use subject pronouns for │
93
+│ the subject of a sentence. │
94
+│ │
95
+│ [Apply] [Ignore] [Dictionary]│
96
+└─────────────────────────────┘
97
+```
98
+
99
+#### Step 4: Apply Changes
100
+- **Apply** - Replace text with suggestion
101
+- **Ignore** - Dismiss this instance
102
+- **Add to Dictionary** - Never flag this word again
103
+
104
+### Grammar Rules Included
105
+
106
+#### Spelling (100+ rules)
107
+- Common misspellings: teh → the
108
+- Missing apostrophes: dont → don't
109
+- Wrong word: alot → a lot
110
+
111
+#### Basic Grammar (35+ rules)
112
+- Pronoun errors: me and him → he and I
113
+- Irregular verbs: buyed → bought
114
+- Their/there/they're confusion
115
+- Your/you're confusion
116
+- Its/it's confusion
117
+
118
+#### Style (50+ rules)
119
+- Passive voice detection
120
+- Weak words: very good → excellent
121
+- Redundant phrases: absolutely essential → essential
122
+- Clichés: think outside the box
123
+
124
+#### Clarity
125
+- Long sentences (>35 words)
126
+- Complex sentence structure
127
+- Hard to read passages
128
+
129
+### Examples
130
+
131
+#### Example 1: Basic Grammar
132
+```
133
+Input: "me and him went to the store"
134
+Output: "he and I went to the store"
135
+ ^^^^^^^^
136
+ Grammar error detected
137
+```
138
+
139
+#### Example 2: Spelling
140
+```
141
+Input: "I dont belive in teh supernatural"
142
+Output: "I don't believe in the supernatural"
143
+ ^^^^ ^^^^^^^ ^^
144
+ 3 spelling errors detected
145
+```
146
+
147
+#### Example 3: Style
148
+```
149
+Input: "The report was written by John yesterday"
150
+Output: "John wrote the report yesterday"
151
+ ^^^^^^^^^^^^^^^
152
+ Passive voice detected
153
+```
154
+
155
+---
156
+
157
+## 🎨 Tone Rewriting
158
+
159
+### Overview
160
+
161
+Rewrite any text in 8 different tones:
162
+
163
+| Tone | Use Case | Example |
164
+|------|----------|---------|
165
+| **Formal** 🎩** | Business, academic | "Hey" → "Greetings" |
166
+| **Casual** 😊 | Friends, chat | "Greetings" → "Hey" |
167
+| **Professional** 💼 | Work emails | "wanna" → "would like to" |
168
+| **Friendly** 🤗 | Social media | "Hello" → "Hey there!" |
169
+| **Concise** ⚡ | Quick messages | "In order to" → "To" |
170
+| **Detailed** 📚 | Explanations | "Go" → "Proceed forward" |
171
+| **Persuasive** 💪 | Sales, pitches | "Try this" → "Experience this" |
172
+| **Neutral** 😐 | General use | Balanced tone |
173
+
174
+### How to Use Tone Rewriting
175
+
176
+#### Method 1: Right-Click Menu
177
+1. Select any text on a webpage
178
+2. Right-click
179
+3. Choose **"Rewrite with OpenGrammar"**
180
+4. Rewrite popup opens
181
+
182
+#### Method 2: Keyboard Shortcut
183
+1. Select text
184
+2. Press `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
185
+3. Rewrite popup opens
186
+
187
+#### Method 3: Extension Menu
188
+1. Click extension icon
189
+2. Click **"Rewrite Text"**
190
+3. Paste or type text
191
+4. Click rewrite
192
+
193
+### Using the Rewrite Popup
194
+
195
+```
196
+┌───────────────────────────────────────┐
197
+│ Rewrite with OpenGrammar [X] │
198
+├───────────────────────────────────────┤
199
+│ │
200
+│ Original Text: │
201
+│ ┌─────────────────────────────────┐ │
202
+│ │ hey whats up can we talk │ │
203
+│ │ │ │
204
+│ └─────────────────────────────────┘ │
205
+│ │
206
+│ Choose Tone: │
207
+│ [Formal] [Casual] [Professional] │
208
+│ [Friendly] [Concise] [Detailed] │
209
+│ [Persuasive] [Neutral] │
210
+│ │
211
+│ ┌─────────────────────────────────┐ │
212
+│ │ Rewritten Text: │ │
213
+│ │ Hello, how are you? May we │ │
214
+│ │ have a conversation? │ │
215
+│ └─────────────────────────────────┘ │
216
+│ │
217
+│ [Apply] [Copy] [Close] │
218
+└───────────────────────────────────────┘
219
+```
220
+
221
+### Step-by-Step Example
222
+
223
+**Original Text:**
224
+```
225
+hey whats up can we talk bout the project
226
+```
227
+
228
+**Step 1: Select Tone**
229
+Click **Professional** 💼
230
+
231
+**Step 2: Click Rewrite**
232
+Wait for AI to process (~1-2 seconds)
233
+
234
+**Step 3: Review Result**
235
+```
236
+Hello, how are you? May we discuss the project?
237
+```
238
+
239
+**Step 4: Apply or Copy**
240
+- **Apply** - Replaces original text
241
+- **Copy** - Copies to clipboard
242
+
243
+### Tips for Tone Rewriting
244
+
245
+✅ **Do:**
246
+- Select complete sentences
247
+- Use appropriate tone for context
248
+- Review before applying
249
+- Try different tones for variety
250
+
251
+❌ **Don't:**
252
+- Rewrite single words (select phrases)
253
+- Use formal tone for casual chats
254
+- Apply without reviewing
255
+- Overuse rewriting
256
+
257
+---
258
+
259
+## 📊 Writing Statistics
260
+
261
+### Overview
262
+
263
+Get detailed insights into your writing:
264
+
265
+### Metrics Available
266
+
267
+#### Basic Counts
268
+- **Words** - Total word count
269
+- **Characters** - Total characters (with/without spaces)
270
+- **Sentences** - Number of sentences
271
+- **Paragraphs** - Number of paragraphs
272
+- **Syllables** - Total syllable count
273
+
274
+#### Readability Scores
275
+
276
+**Flesch Reading Ease** (0-100)
277
+```
278
+90-100: Very Easy (5th grade)
279
+80-89: Easy (6th grade)
280
+70-79: Fairly Easy (7th grade)
281
+60-69: Standard (8th-9th grade)
282
+50-59: Fairly Difficult (10th-12th grade)
283
+30-49: Difficult (College)
284
+0-29: Very Difficult (College Graduate+)
285
+```
286
+
287
+**Flesch-Kincaid Grade Level**
288
+```
289
+1-6: Elementary
290
+7-9: Middle School
291
+10-12: High School
292
+13-16: College
293
+17+: Graduate
294
+```
295
+
296
+**Automated Readability Index (ARI)**
297
+```
298
+1-6: Ages 5-12
299
+7-9: Ages 12-15
300
+10-12: Ages 15-18
301
+13+: Ages 18+
302
+```
303
+
304
+#### Time Estimates
305
+- **Reading Time** - Based on 200 words per minute
306
+- **Speaking Time** - Based on 150 words per minute
307
+
308
+#### Vocabulary Analysis
309
+- **Unique Words** - Number of different words
310
+- **Vocabulary Diversity** - Percentage of unique words
311
+- **Average Word Length** - Mean characters per word
312
+
313
+### Accessing Statistics
314
+
315
+#### Method 1: Extension Popup
316
+1. Click extension icon
317
+2. Click **Statistics** tab
318
+3. View real-time stats
319
+
320
+#### Method 2: Options Page
321
+1. Right-click extension icon
322
+2. Choose **Options**
323
+3. Navigate to **Statistics** section
324
+
325
+#### Method 3: Keyboard Shortcut
326
+(If configured)
327
+1. Press shortcut
328
+2. Statistics popup appears
329
+
330
+### Example Statistics Report
331
+
332
+```
333
+┌─────────────────────────────────────┐
334
+│ Writing Statistics │
335
+├─────────────────────────────────────┤
336
+│ │
337
+│ Basic Counts │
338
+│ ─────────────────────────────────── │
339
+│ Words: 1,248 │
340
+│ Characters: 6,542 │
341
+│ Sentences: 87 │
342
+│ Paragraphs: 12 │
343
+│ │
344
+│ Readability │
345
+│ ─────────────────────────────────── │
346
+│ Flesch Ease: 78 (Excellent) │
347
+│ Grade Level: 8.5 (Good) │
348
+│ ARI: 9 (Good) │
349
+│ │
350
+│ Time Estimates │
351
+│ ─────────────────────────────────── │
352
+│ Reading Time: 4 minutes │
353
+│ Speaking Time: 6 minutes │
354
+│ │
355
+│ Vocabulary │
356
+│ ─────────────────────────────────── │
357
+│ Unique Words: 542 │
358
+│ Diversity: 43% (Good) │
359
+│ Avg Word Length: 4.8 characters │
360
+│ │
361
+│ Issue Breakdown │
362
+│ ─────────────────────────────────── │
363
+│ Grammar: 3 issues 🔴 │
364
+│ Clarity: 5 issues 🟡 │
365
+│ Style: 7 issues 🔵 │
366
+└─────────────────────────────────────┘
367
+```
368
+
369
+### Improving Your Score
370
+
371
+**To Improve Readability:**
372
+1. Shorten long sentences
373
+2. Use simpler words
374
+3. Break up paragraphs
375
+4. Reduce passive voice
376
+
377
+**To Improve Vocabulary:**
378
+1. Use synonyms for repeated words
379
+2. Vary sentence structure
380
+3. Learn new words
381
+4. Read diverse content
382
+
383
+---
384
+
385
+## 📚 Custom Dictionary
386
+
387
+### Overview
388
+
389
+Add words that OpenGrammar should never flag as errors:
390
+- Proper nouns (names, places)
391
+- Technical terms
392
+- Industry jargon
393
+- Made-up words
394
+
395
+### Managing Your Dictionary
396
+
397
+#### Add Words
398
+
399
+**Method 1: From Suggestion Popup**
400
+1. Click underlined word
401
+2. Click **Add to Dictionary**
402
+3. Word is saved
403
+
404
+**Method 2: Options Page**
405
+1. Right-click extension → Options
406
+2. Go to **Custom Dictionary**
407
+3. Click **Add Word**
408
+4. Enter word
409
+5. Click **Save**
410
+
411
+**Method 3: Bulk Import**
412
+1. Options → Custom Dictionary
413
+2. Click **Import**
414
+3. Upload text file (one word per line)
415
+4. Words are added
416
+
417
+#### Remove Words
418
+
419
+1. Options → Custom Dictionary
420
+2. Find word in list
421
+3. Click **Remove** (trash icon)
422
+4. Confirm deletion
423
+
424
+#### Export Dictionary
425
+
426
+1. Options → Custom Dictionary
427
+2. Click **Export**
428
+3. Download JSON file
429
+4. Save for backup
430
+
431
+### Dictionary Tips
432
+
433
+✅ **Good Words to Add:**
434
+- Your name
435
+- Company names
436
+- Product names
437
+- Technical terminology
438
+- Common abbreviations you use
439
+
440
+❌ **Don't Add:**
441
+- Common misspellings
442
+- Offensive words
443
+- Temporary terms
444
+
445
+### Example Dictionary
446
+
447
+```
448
+My Custom Dictionary (127 words)
449
+─────────────────────────────────
450
+✓ opengrammar
451
+✓ typescript
452
+✓ javascript
453
+✓ swadhin
454
+✓ api
455
+✓ backend
456
+✓ frontend
457
+✓ devops
458
+✓ kubernetes
459
+✓ docker
460
+...
461
+
462
+[Add Word] [Import] [Export] [Clear All]
463
+```
464
+
465
+---
466
+
467
+## 🌐 Site-Specific Settings
468
+
469
+### Overview
470
+
471
+Control OpenGrammar behavior per website:
472
+- Disable on specific domains
473
+- Different settings per site
474
+- Automatic detection
475
+
476
+### Disabling Sites
477
+
478
+#### Method 1: Quick Disable
479
+1. Click extension icon
480
+2. Toggle **Enable on this site**
481
+3. Site is added to disabled list
482
+
483
+#### Method 2: Options Page
484
+1. Right-click extension → Options
485
+2. Go to **Site-Specific Settings**
486
+3. Click **Add Domain**
487
+4. Enter domain (e.g., `twitter.com`)
488
+5. Toggle enabled/disabled
489
+6. Click **Save**
490
+
491
+### Managing Disabled Sites
492
+
493
+```
494
+Site-Specific Settings
495
+─────────────────────────────────────
496
+✓ gmail.com [Disable] [Remove]
497
+✓ docs.google.com [Disable] [Remove]
498
+✓ notion.so [Disable] [Remove]
499
+✗ twitter.com [Enable] [Remove]
500
+✗ facebook.com [Enable] [Remove]
501
+
502
+[Add Domain] [Disable All] [Enable All]
503
+```
504
+
505
+### When to Disable
506
+
507
+**Good Candidates:**
508
+- Social media (casual writing)
509
+- Code editors (technical text)
510
+- Gaming sites (chat)
511
+- Sites with custom text inputs
512
+
513
+**Keep Enabled:**
514
+- Email clients
515
+- Document editors
516
+- Writing tools
517
+- Forms and applications
518
+
519
+---
520
+
521
+## ⌨️ Keyboard Shortcuts
522
+
523
+### Default Shortcuts
524
+
525
+| Action | Windows/Linux | Mac |
526
+|--------|---------------|-----|
527
+| **Rewrite Selected Text** | `Ctrl+Shift+R` | `Cmd+Shift+R` |
528
+| **Toggle Extension** | `Ctrl+Shift+E` | `Cmd+Shift+E` |
529
+| **Open Statistics** | `Ctrl+Shift+S` | `Cmd+Shift+S` |
530
+| **Open Settings** | `Ctrl+Shift+,` | `Cmd+Shift+,` |
531
+
532
+### Customizing Shortcuts
533
+
534
+#### Chrome/Brave/Edge
535
+1. Go to `chrome://extensions/shortcuts`
536
+2. Find OpenGrammar
537
+3. Click shortcut field
538
+4. Press new key combination
539
+5. Click **Save**
540
+
541
+#### Firefox
542
+1. Go to `about:addons`
543
+2. Click gear icon → **Manage Extension Shortcuts**
544
+3. Find OpenGrammar
545
+4. Set new shortcuts
546
+
547
+### Shortcut Tips
548
+
549
+✅ **Best Practices:**
550
+- Use memorable combinations
551
+- Avoid system shortcuts
552
+- Keep hands on home row
553
+- Practice muscle memory
554
+
555
+❌ **Avoid:**
556
+- `Ctrl+C`, `Ctrl+V` (copy/paste)
557
+- `Ctrl+Z` (undo)
558
+- `Ctrl+T` (new tab)
559
+- Browser-reserved shortcuts
560
+
561
+---
562
+
563
+## 💡 Tips & Best Practices
564
+
565
+### Daily Usage Tips
566
+
567
+#### 1. Start with Rule-Based Only
568
+- No API key needed
569
+- Works offline
570
+- Catches basic errors
571
+- Fast and free
572
+
573
+#### 2. Add AI for Complex Writing
574
+- Use for important emails
575
+- Enable for documents
576
+- Disable for casual chat
577
+- Choose right model
578
+
579
+#### 3. Build Your Dictionary
580
+- Add names early
581
+- Include technical terms
582
+- Import from other tools
583
+- Sync across devices
584
+
585
+#### 4. Use Tone Rewriting Wisely
586
+- Professional for work
587
+- Casual for friends
588
+- Concise for messages
589
+- Formal for documents
590
+
591
+#### 5. Check Statistics Regularly
592
+- Monitor readability
593
+- Track vocabulary
594
+- Set improvement goals
595
+- Compare documents
596
+
597
+### Workflow Integration
598
+
599
+#### For Email
600
+1. Compose in Gmail
601
+2. Wait for grammar check
602
+3. Review suggestions
603
+4. Apply important fixes
604
+5. Use tone rewriting for polish
605
+
606
+#### For Documents
607
+1. Write in Google Docs
608
+2. Enable full checking
609
+3. Review all suggestions
610
+4. Check statistics
611
+5. Rewrite key sections
612
+
613
+#### For Social Media
614
+1. Disable on casual sites
615
+2. Enable for professional posts
616
+3. Use concise tone
617
+4. Quick grammar check only
618
+
619
+#### For Coding/Technical
620
+1. Disable in code editors
621
+2. Enable for comments/docs
622
+3. Add technical terms to dictionary
623
+4. Use custom rules
624
+
625
+### Common Mistakes to Avoid
626
+
627
+❌ **Over-relying on AI**
628
+- Review all suggestions
629
+- Understand the changes
630
+- Learn from mistakes
631
+- Don't accept blindly
632
+
633
+❌ **Ignoring Context**
634
+- Consider your audience
635
+- Match tone to situation
636
+- Keep your voice
637
+- Don't over-edit
638
+
639
+❌ **Not Customizing**
640
+- Add domain-specific terms
641
+- Adjust settings per site
642
+- Configure shortcuts
643
+- Personalize dictionary
644
+
645
+❌ **Skipping Statistics**
646
+- Check readability
647
+- Monitor progress
648
+- Set goals
649
+- Track improvements
650
+
651
+### Advanced Tips
652
+
653
+#### 1. Hybrid Mode
654
+Use both engines:
655
+- Rules for basic errors (free, fast)
656
+- AI for complex issues (smart, contextual)
657
+
658
+#### 2. Batch Processing
659
+For long documents:
660
+- Write first draft
661
+- Enable checking
662
+- Review all at once
663
+- Apply in batches
664
+
665
+#### 3. Custom Prompts
666
+(If supported)
667
+- Create custom instructions
668
+- Save favorite tones
669
+- Set default styles
670
+- Automate common tasks
671
+
672
+#### 4. Export & Backup
673
+Regularly:
674
+- Export settings
675
+- Backup dictionary
676
+- Save statistics
677
+- Document custom rules
678
+
679
+---
680
+
681
+## 🆘 Troubleshooting
682
+
683
+### Common Issues
684
+
685
+**Problem:** No underlines appear
686
+
687
+**Solutions:**
688
+1. Check extension is enabled
689
+2. Verify site not disabled
690
+3. Test backend connection
691
+4. Reload page
692
+5. Check browser console
693
+
694
+**Problem:** Suggestions not applying
695
+
696
+**Solutions:**
697
+1. Click directly on suggestion
698
+2. Wait for popup to load
699
+3. Check permissions
700
+4. Try keyboard shortcut
701
+5. Restart browser
702
+
703
+**Problem:** Rewrite not working
704
+
705
+**Solutions:**
706
+1. Select text first
707
+2. Check API key valid
708
+3. Verify backend running
709
+4. Try different tone
710
+5. Check network connection
711
+
712
+---
713
+
714
+## 📚 Related Documentation
715
+
716
+- [Browser Setup](04-browser-extension-setup.md) - Install on your browser
717
+- [AI Providers](07-ai-providers.md) - Configure AI
718
+- [Tone Rewriting](10-tone-rewriting.md) - Detailed rewriting guide
719
+- [Troubleshooting](18-troubleshooting.md) - Fix common issues
720
+
721
+---
722
+
723
+**Happy Writing! ✨**
724
+
725
+OpenGrammar is your companion for clear, confident writing. Use it wisely, customize it to your needs, and watch your writing improve!
0
726