# Survey Builder - Quick Start Guide

## 🚀 Get Started in 3 Minutes

### Step 1: Run Migration (One Time Only)
1. Open your browser
2. Navigate to: `yoursite.com/scripts/run_survey_builder_migration.php`
3. Log in as admin
4. Migration runs automatically
5. You'll see a success message

### Step 2: Create Your First Survey
1. Go to **Studies** page
2. Click **📋 Survey** on any study
3. Click **+ Add Question**
4. Fill in your question
5. Choose question type
6. Click **Add Question**

### Step 3: Activate & Test
1. Check the box: "Show this survey to participants"
2. Click **Save Settings**
3. Click **👁️ Preview Survey** to test
4. Complete a study session to see it in action

---

## 📝 Quick Examples

### Example 1: Simple 3-Question Survey
```
Q1: "How easy was this task?"
Type: 5-Star Rating
Required: Yes

Q2: "What worked well?"  
Type: Long Text
Required: No

Q3: "What needs improvement?"
Type: Long Text
Required: No
```

### Example 2: NPS Survey
```
Q1: "How likely are you to recommend this product?"
Type: Scale (0-10)
Min Label: "Not likely"
Max Label: "Very likely"
Required: Yes

Q2: "What's the main reason for your score?"
Type: Long Text  
Required: Yes
```

### Example 3: Feature Selection
```
Q1: "Which features would you use regularly?"
Type: Checkbox (Select all that apply)
Options:
  □ Dark mode
  □ Offline access
  □ Push notifications
  □ Export data
  □ Keyboard shortcuts
Required: No

Q2: "Which feature is most important?"
Type: Multiple Choice (Select one)
Options (same as above)
Required: Yes
```

---

## 📊 6 Question Types

| Type | Best For | Example |
|------|----------|---------|
| **Text** | Short answers | "What would you call this feature?" |
| **Textarea** | Detailed feedback | "Describe your experience..." |
| **Multiple Choice** | Single selection | "What's your role?" |
| **Checkbox** | Multi-selection | "Select all that apply" |
| **Rating** | Quick feedback | "Rate your experience ★★★★★" |
| **Scale** | NPS, likelihood | "0-10: How likely..." |

---

## ✅ Tips for Great Surveys

**DO:**
- ✅ Keep it short (3-7 questions)
- ✅ Mix question types for variety
- ✅ Use required sparingly (only critical questions)
- ✅ Test your survey before going live

**DON'T:**
- ❌ Make every question required
- ❌ Ask more than 10 questions
- ❌ Use jargon or technical terms
- ❌ Forget to activate the survey!

---

## 🔧 Common Tasks

### Add Options to Multiple Choice
1. Click **+ Add Question**
2. Select "Multiple Choice" or "Checkbox"
3. Enter first option
4. Click **+ Add Option** for each additional choice
5. Click **Add Question**

### Create a Scale Question
1. Click **+ Add Question**
2. Select "Numeric Scale"
3. Set Min value (e.g., 0)
4. Set Max value (e.g., 10)
5. Add labels (optional): "Not likely" and "Very likely"
6. Click **Add Question**

### Make a Question Optional
1. When creating/editing a question
2. Uncheck "Required question (participants must answer)"
3. Click **Add/Save Question**

### Reorder Questions
Currently questions display in creation order. To reorder:
1. Note the question text you want to move
2. Delete the question
3. Create it again in the desired position

---

## 🎯 Study-Specific Templates

### For Card Sorts
```
1. "Were any card labels unclear?" (Long Text, Optional)
2. "Which category was hardest to name?" (Multiple Choice, Required)
3. "Rate your confidence" (5-Star Rating, Required)
```

### For Tree Tests
```
1. "Which task was most difficult?" (Multiple Choice, Required)
2. "Were any menu labels confusing?" (Long Text, Optional)
3. "Rate the navigation structure" (Scale 1-10, Required)
```

### For Prototype Tests
```
1. "Overall impression" (Long Text, Optional)
2. "Which features would you use?" (Checkbox, Optional)
3. "Ease of completing the task" (Scale 1-7, Required)
4. "Rate the visual design" (5-Star Rating, Required)
```

---

## 📈 Viewing Results

1. Click **Studies** in main menu
2. Select your study
3. Click **Reports** tab
4. Click **Survey Results**
5. View responses by question or by participant
6. Export to CSV for further analysis

---

## ⚠️ Troubleshooting

**Survey not showing to participants?**
- Check that survey is marked "Active" in settings
- Ensure at least one question exists
- Complete a full study session to reach thank you page

**Can't add options to question?**
- Make sure you selected "Multiple Choice" or "Checkbox" type
- Click "+ Add Option" button to add more choices

**Responses not saving?**
- Check browser console for errors
- Verify database migration ran successfully
- Ensure network connection is stable

---

## 🆕 What's New vs. Old Survey System?

| Feature | Old System | New System |
|---------|------------|------------|
| Questions | Fixed 5 questions | Unlimited |
| Question Types | Text only | 6 types |
| Customization | Limited | Full control |
| Answer Options | N/A | Custom options |
| Required/Optional | All optional | Per-question |
| Visual Widgets | No | Stars, scales |

---

## Need More Help?

See the complete **SURVEY_BUILDER_GUIDE.md** for:
- Detailed question type documentation
- API endpoints
- Database schema
- Advanced techniques
- Best practices
- Full troubleshooting guide

---

**Ready to start?** → Go to Studies → Click 📋 Survey → Add your first question!