update help documentation and re-enable hints in settings
This commit is contained in:
jonasgaudian
270
docs/EXERCISES.md
Normal file
270
docs/EXERCISES.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Vocabulary Exercises Documentation
|
||||
|
||||
This document explains how the exercise system works in the Polly vocabulary learning app.
|
||||
|
||||
## Overview
|
||||
|
||||
The exercise system allows users to practice vocabulary through various interactive exercise types. Users can configure and start exercises from different screens, track their progress, and review their results.
|
||||
|
||||
## Exercise Types
|
||||
|
||||
The app supports four different exercise types:
|
||||
|
||||
### 1. Guessing Exercise (Flashcard Mode)
|
||||
|
||||
**How it works:**
|
||||
- A vocabulary card is displayed with one side (word or translation)
|
||||
- The user sees only one side of the card initially
|
||||
- The user guesses the answer before flipping the card
|
||||
|
||||
**User actions:**
|
||||
- Tap "Flip Card" to reveal the answer
|
||||
- Mark as "Wrong" or "Correct" after revealing
|
||||
- The card advances when "Next" is tapped
|
||||
|
||||
**Use case:** Ideal for quick recognition practice and memorization.
|
||||
|
||||
---
|
||||
|
||||
### 2. Spelling Exercise
|
||||
|
||||
**How it works:**
|
||||
- A vocabulary word is displayed as a prompt
|
||||
- The user must type the translation manually
|
||||
- The app checks if the typed answer is correct
|
||||
|
||||
**User actions:**
|
||||
- Type the translation in the text field
|
||||
- Tap "Check" to submit the answer
|
||||
- See immediate feedback on correctness
|
||||
- Tap "Next" to proceed to the next card
|
||||
|
||||
**Use case:** Excellent for practicing proper spelling and reinforcing memory through active recall.
|
||||
|
||||
---
|
||||
|
||||
### 3. Multiple Choice Exercise
|
||||
|
||||
**How it works:**
|
||||
- A word is displayed with four answer options
|
||||
- Only one option is the correct translation
|
||||
- The user selects their answer
|
||||
|
||||
**User actions:**
|
||||
- Tap one of the four options
|
||||
- The correct answer is highlighted after selection
|
||||
- Visual feedback shows if the choice was right or wrong
|
||||
- Tap "Next" to continue
|
||||
|
||||
**Use case:** Good for recognition practice with immediate feedback.
|
||||
|
||||
---
|
||||
|
||||
### 4. Word Jumble Exercise
|
||||
|
||||
**How it works:**
|
||||
- A word's letters are scrambled and displayed
|
||||
- The user must click letters in the correct order to form the word
|
||||
- Letters can be moved between the "available" and "assembled" areas
|
||||
|
||||
**User actions:**
|
||||
- Click a letter from the available pool to add it to the assembly area
|
||||
- Click an assembled letter to return it to the pool
|
||||
- Tap "Check" when the word is assembled
|
||||
- The correct answer is revealed if incorrect
|
||||
|
||||
**Use case:** Great for reinforcing spelling through active manipulation of letter order.
|
||||
|
||||
---
|
||||
|
||||
## Starting an Exercise
|
||||
|
||||
### Entry Points
|
||||
|
||||
1. **Dashboard Widget:** Tap "Start Exercise" from the ModernStartButtons widget
|
||||
2. **Category Detail Screen:** Tap "Start" on a specific category
|
||||
3. **Main Vocabulary Screen:** Tap the FAB (Floating Action Button)
|
||||
4. **Daily Exercise:** Access from the dashboard for daily review
|
||||
|
||||
### Configuration Options
|
||||
|
||||
Before starting an exercise, users can configure:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| **Number of Cards** | Slider to select how many cards to practice (1 to total available) |
|
||||
| **Quick Select** | Preset buttons for 10, 25, 50, or 100 cards |
|
||||
| **Language Direction** | Choose origin and target languages |
|
||||
| **Exercise Types** | Select which exercise types to include (can combine multiple) |
|
||||
| **Shuffle Cards** | Randomize card order |
|
||||
| **Shuffle Languages** | Randomize which side (word/translation) is shown |
|
||||
| **Training Mode** | Practice without affecting progress/stages |
|
||||
| **Due Today Only** | Limit to items scheduled for today |
|
||||
|
||||
---
|
||||
|
||||
## Exercise Flow
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ START SCREEN │
|
||||
│ (Configuration) │
|
||||
└────────┬────────┘
|
||||
│ Tap "Start Exercise"
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ EXERCISE │
|
||||
│ PROGRESS │
|
||||
│ INDICATOR │
|
||||
├─────────────────┤
|
||||
│ CARD/QUESTION │
|
||||
│ DISPLAY │
|
||||
├─────────────────┤
|
||||
│ CONTROLS │
|
||||
│ (Reveal/Check) │
|
||||
└────────┬────────┘
|
||||
│ Complete all cards
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ RESULT SCREEN │
|
||||
│ (Score, │
|
||||
│ Retry, │
|
||||
│ Start Over) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exercise Progress Indicator
|
||||
|
||||
During an exercise, a progress bar shows:
|
||||
|
||||
- **Green section:** Number of correct answers
|
||||
- **Red section:** Number of wrong answers
|
||||
- **Total:** Total cards in the exercise
|
||||
- **Close button:** Exit the exercise (shows confirmation dialog)
|
||||
|
||||
The progress bar animates as the user advances through cards.
|
||||
|
||||
---
|
||||
|
||||
## Exercise State Management
|
||||
|
||||
The app uses a state machine to manage exercise progress:
|
||||
|
||||
### States
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| `START` | Configuration screen before starting |
|
||||
| `EXERCISE` | Active exercise in progress |
|
||||
| `RESULT` | Exercise completed, showing results |
|
||||
|
||||
### State Transitions
|
||||
|
||||
```
|
||||
START → EXERCISE (user taps "Start")
|
||||
EXERCISE → RESULT (all cards completed)
|
||||
RESULT → START (user taps "Start Over")
|
||||
RESULT → EXERCISE (user taps "Retry Wrong")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exercise Actions
|
||||
|
||||
The following user actions are available during exercises:
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `Reveal` | Show the answer (Guessing exercise) |
|
||||
| `Submit` | Submit an answer (Spelling, Multiple Choice, Word Jumble) |
|
||||
| `Next` | Move to the next card |
|
||||
| `UpdateWordJumble` | Modify assembled letters (Word Jumble) |
|
||||
|
||||
---
|
||||
|
||||
## Results Screen
|
||||
|
||||
After completing an exercise, users see:
|
||||
|
||||
### Displayed Information
|
||||
- **Percentage Score:** Overall performance as a circular progress indicator
|
||||
- **Correct/Wrong Count:** Detailed breakdown of answers
|
||||
- **Total Items:** Number of cards practiced
|
||||
|
||||
### Available Actions
|
||||
- **Start Over:** Begin a new exercise from scratch
|
||||
- **Repeat Wrong:** Retry only the incorrectly answered cards
|
||||
- **Finish:** Return to the main screen
|
||||
|
||||
---
|
||||
|
||||
## Training Mode
|
||||
|
||||
When Training Mode is enabled:
|
||||
- Answers are not recorded for progress tracking
|
||||
- No stage progression occurs
|
||||
- Useful for casual practice or testing knowledge
|
||||
|
||||
When disabled (default):
|
||||
- Correct answers may advance item stages
|
||||
- Progress is saved for statistics
|
||||
- Affects due dates and learning progress
|
||||
|
||||
---
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **VocabularyExerciseHostScreen.kt**
|
||||
- Main container managing exercise flow
|
||||
- Handles screen states (START, EXERCISE, RESULT)
|
||||
- Coordinates between configuration and exercise screens
|
||||
|
||||
2. **VocabularyExercise.kt**
|
||||
- Defines exercise types (enum)
|
||||
- State classes for each exercise type
|
||||
- Action sealed class for user interactions
|
||||
|
||||
3. **VocabularyExerciseRenderer.kt**
|
||||
- Renders the appropriate UI based on exercise state
|
||||
- Handles display logic for each exercise type
|
||||
|
||||
4. **ExerciseControls.kt**
|
||||
- Input field and buttons for user interaction
|
||||
- Different controls based on exercise type
|
||||
|
||||
5. **ExerciseProgressIndicator.kt**
|
||||
- Visual progress bar during exercises
|
||||
- Animated updates for correct/wrong counts
|
||||
|
||||
---
|
||||
|
||||
## Related Screens
|
||||
|
||||
| Screen | Purpose |
|
||||
|--------|---------|
|
||||
| `StartScreen` | Configure exercise settings before starting |
|
||||
| `ResultScreen` | Show final score and options to continue |
|
||||
| `CategoryDetailScreen` | Start exercise for a specific category |
|
||||
| `DashboardContent` | Main dashboard with exercise shortcuts |
|
||||
|
||||
---
|
||||
|
||||
## Tips for Users
|
||||
|
||||
1. **Combine exercise types:** Mix Guessing, Spelling, and Word Jumble for variety
|
||||
2. **Use Training Mode:** For casual practice without affecting progress
|
||||
3. **Start small:** Use 10-25 cards initially, increase as comfortable
|
||||
4. **Review wrong answers:** Use "Repeat Wrong" to focus on difficult items
|
||||
5. **Daily exercises:** Use "Due Today Only" for spaced repetition practice
|
||||
|
||||
---
|
||||
|
||||
## Navigation During Exercise
|
||||
|
||||
- **Close button:** Exit exercise (confirms before closing)
|
||||
- **Back button:** Also triggers exit confirmation
|
||||
- Results screen options: Continue practicing or return to dashboard
|
||||
Reference in New Issue
Block a user