Create Tutorial

Create comprehensive, learner-centered tutorials for the VRP Toolkit project.

Core Philosophy

Tutorials are progressive learning experiences, not documentation dumps. They should:

• Start simple, build complexity gradually
• Emphasize hands-on practice over theory
• Show real, runnable code
• Explain the “why” not just the “how”

Tutorial Categories

1. Feature Tutorials (How to use X)

Examples: “How to use OSMnx integration”, “How to visualize routes”

• Focus on one specific feature
• Show multiple use cases
• Include troubleshooting

2. Concept Tutorials (Understanding X)

Examples: “Custom problems explained”, “Algorithm configuration”

• Explain underlying concepts
• Compare alternatives
• Show when to use what

3. Task Tutorials (Build X)

Examples: “Build a custom heuristic”, “Create CVRP variant”

• Goal-oriented, project-based
• Step-by-step construction
• Final working artifact

4. Integration Tutorials (Combine X + Y)

Examples: “Real maps + custom algorithms”, “Benchmarking workflow”

• Show how pieces fit together
• Realistic workflows
• Best practices

Tutorial Structure Template

Use this structure for all tutorials:

Section 1: Introduction (2-3 minutes read)

# Tutorial XX: [Clear, Action-Oriented Title]

[2-3 sentence overview of what student will learn]

**What you'll learn:**
- Concrete skill 1
- Concrete skill 2
- Concrete skill 3

**Prerequisites:**
- Tutorial YY (if applicable)
- Basic Python knowledge

**Time:** ~XX minutes

Section 2: Setup (5 minutes)

## 1. Setup and Imports

[Minimal imports needed - copy-pasteable]

```python
# Standard imports
import numpy as np
import pandas as pd

# VRP Toolkit imports
from vrp_toolkit.xxx import yyy

[Quick validation – ensure imports work]

### Section 3: Quick Win (10 minutes)
```markdown
## 2. Quick Start: [Simplest Possible Example]

Let's start with the **simplest possible example** to see it working:

[Code that runs in <10 lines and produces visible output]

**What just happened:**
[Brief explanation of what the code did]

Critical: Student should get a working result in first 10 minutes.

Section 4: Core Concepts (15-20 minutes)

## 3. Understanding [Key Concept]

Now let's understand what's really happening.

### 3.1 [Sub-concept 1]
[Explanation]
[Code example]

### 3.2 [Sub-concept 2]
[Explanation]
[Code example]

### 3.3 [Sub-concept 3]
[Explanation]
[Code example]

Progressive disclosure: Introduce complexity one piece at a time.

Section 5: Advanced Usage (10-15 minutes)

## 4. Advanced Features

Now that you understand the basics, let's explore advanced options:

### 4.1 [Advanced Feature 1]
**When to use:** [Specific scenario]
**How it works:** [Brief explanation]

```python
[Code example]

4.2 [Advanced Feature 2]

[Similar structure]

### Section 6: Real-World Example (10-15 minutes)
```markdown
## 5. Real-World Example: [Concrete Scenario]

Let's apply everything to a realistic scenario:

**Scenario:** [Describe a real problem]

[Complete, runnable example that combines concepts]

**Key observations:**
- Point 1
- Point 2

Section 7: Comparison & When to Use (5 minutes)

## 6. Comparison and Best Practices

**When to use [this approach]:**
- Scenario 1
- Scenario 2

**When to use [alternative]:**
- Scenario 3
- Scenario 4

**Common pitfalls:**
- Pitfall 1 and how to avoid it
- Pitfall 2 and how to avoid it

Section 8: Exercises (Optional)

## 7. Practice Exercises

Try these on your own:

1. **Basic:** [Simple modification task]
2. **Intermediate:** [Combine concepts]
3. **Advanced:** [Open-ended challenge]

[Hints or solution sketches]

Section 9: Summary & Next Steps

## 8. Summary

**What you learned:**
- ✅ Skill 1
- ✅ Skill 2
- ✅ Skill 3

**Key takeaways:**
1. Important insight 1
2. Important insight 2

**Next steps:**
- Try Tutorial XX for [related topic]
- Explore [related feature]
- Build your own [project idea]

Code Quality Standards

All code must be:

1. Runnable – Copy-paste works without modification
2. Realistic – Uses actual VRP toolkit APIs (not pseudo-code)
3. Minimal – Shortest code that demonstrates the concept
4. Commented – Explain non-obvious parts

Code Examples Structure:

# Step 1: [What this does]
code_line_1

# Step 2: [What this does]
code_line_2

# Verify result
print(f"Result: {result}")  # Show output

Best Practices

DO:

✅ Start with working code, explain after ✅ Use consistent variable names across examples ✅ Show output for every code block ✅ Explain errors students might encounter ✅ Compare alternatives (“X vs Y”) ✅ Include visual output (plots, tables) ✅ Build on previous tutorials

DON’T:

❌ Start with theory before showing code ❌ Assume prior knowledge (state prerequisites) ❌ Use complex examples too early ❌ Skip error handling in advanced sections ❌ Leave code unexplained ❌ Use pseudo-code instead of real code

Tutorial Naming Convention

XX_topic_name.ipynb

Where:
- XX = Tutorial number (01, 02, 03, ...)
- topic_name = snake_case description

Examples:

• 03_custom_problems.ipynb
• 04_problem_variants.ipynb
• 06_custom_algorithms.ipynb

Creating a New Tutorial: Step-by-Step

1. Define Learning Objectives

Ask yourself:

• What specific skill will students have after this?
• What can they build that they couldn’t before?
• What prerequisite knowledge is needed?

2. Create the Notebook

# Create new Jupyter notebook
touch tutorials/XX_topic_name.ipynb

3. Follow the Template

Use the structure template above, adapting as needed for the topic.

4. Test Every Code Block

• Run all cells in order
• Verify output matches what’s described
• Test on fresh Python environment

5. Review Checklist

Before finalizing, verify:

• Title clearly states what student will learn
• Prerequisites are stated upfront
• First example works within 10 minutes
• All code blocks run without errors
• Code examples use actual VRP toolkit APIs
• Each concept builds on previous ones
• Output is shown for all code examples
• Common errors are addressed
• Summary lists concrete skills learned
• Next steps are suggested

6. Integration

• Add to README.md tutorial list
• Update tutorial numbering if needed
• Test links between tutorials

Topic-Specific Guidance

For Problem Creation Tutorials:

• Show multiple input formats (CSV, manual, generated)
• Demonstrate validation and error checking
• Compare with built-in examples
• Show how to visualize the problem

For Algorithm Tutorials:

• Explain the algorithm intuition first
• Show simplest version, then add complexity
• Compare with baseline (greedy, random)
• Demonstrate configuration options
• Include performance comparisons

For Integration Tutorials:

• Start with working individual pieces
• Show integration points clearly
• Explain why integration is beneficial
• Provide complete end-to-end example

Quality Metrics

A good tutorial:

• Time-to-first-win < 10 minutes
• Code-to-text ratio > 30%
• Student can build something after completion
• Progressive complexity (easy → medium → hard)
• All code runs without errors

Example Tutorial Outline

See references/example-tutorial-outline.md for a complete example of applying this template.

Resources

• Template notebook: assets/tutorial-template.ipynb
• Example tutorial: references/example-tutorial-outline.md
• Learning principles: references/learning-principles.md

Usage Workflow

When user requests a tutorial:

1. Clarify scope – What should students learn?
2. Identify category – Feature/Concept/Task/Integration?
3. Check prerequisites – What do students need to know first?
4. Follow template – Use structure above
5. Write code first – Then add explanations
6. Test thoroughly – Run all cells
7. Review checklist – Ensure quality standards
8. Integrate – Add to README and cross-link

Tutorial Maintenance

When updating existing tutorials:

• Maintain backward compatibility in code examples
• Update for API changes
• Add clarifications based on user feedback
• Keep examples realistic and current