# Documentation Index

Complete guide to all documentation in this repository.

## 📖 **For Different Audiences**

### 🎯 **Business Users / Non-Technical**

Start here if you want to solve a problem but don't know much about MDPs or programming:

1. **[Practical Guide](PRACTICAL_GUIDE.md)** ⭐ START HERE
   - Simple explanations of real examples
   - How to recognize if this tool can help you
   - What questions it answers
   - Key lessons and insights
2. **[JSON Configuration Guide](JSON_GUIDE.md)** (General-Purpose Format)
   - For business/engineering problems (manufacturing, DevOps, finance)
   - Complete format reference
   - Common patterns and tips

### 💻 **Developers / Technical Users**

1. **[QUICKSTART.md](../QUICKSTART.md)** - Installation and first run (canonical)
2. **[README.md](../README.md)** - Main documentation
   - API reference (canonical)
   - CLI reference (canonical)
   - Python examples

3. **[JSON Configuration Guide](JSON_GUIDE.md)** (General-Purpose)

   - General-purpose MDP JSON format
   - Works with CLI (`python3 -m upo.cli`) and Python API

4. **[Implementation Notes](IMPLEMENTATION_NOTES.md)**
   - Project summary (at a glance)
   - Design decisions
   - Algorithm complexity
   - Validation strategy

### 🎓 **Researchers / Students**

1. **[Algorithm Walkthrough](WALKTHROUGH.md)**

   - Mathematical explanation
   - Bellman optimality equation
   - Value iteration algorithm
   - Worked example

2. **[Implementation Notes](IMPLEMENTATION_NOTES.md)**

   - Computational complexity
   - Convergence properties
   - Edge cases

3. **[Verification Tests](../tests/VERIFICATION.md)**
   - Algorithm verification
   - Analytically solvable test cases
   - What each test proves

---

## 📚 **By Topic**

### **Getting Started**

| Document                              | Purpose                              |
| ------------------------------------- | ------------------------------------ |
| [Practical Guide](PRACTICAL_GUIDE.md) | Understand when/how to use this tool |
| [Quick Start Guide](../QUICKSTART.md) | Install and run your first example   |
| [JSON Guide](JSON_GUIDE.md)           | General-purpose MDP format           |

### **Understanding the Math**

| Document                                        | Purpose                          |
| ----------------------------------------------- | -------------------------------- |
| [Algorithm Walkthrough](WALKTHROUGH.md)         | Mathematical explanation         |
| [Verification Tests](../tests/VERIFICATION.md)  | See the algorithm proven correct |
| [Implementation Notes](IMPLEMENTATION_NOTES.md) | Design and complexity            |

### **Using the Library**

| Document                                                 | Purpose                     |
| -------------------------------------------------------- | --------------------------- |
| [README API Reference](../README.md#api-reference)       | Python API usage            |
| [JSON Guide](JSON_GUIDE.md)                              | General-purpose JSON format |
| [CLI Documentation](../README.md#command-line-interface) | Command-line usage          |

### **Examples**

| Document                                                                            | Purpose                       |
| ----------------------------------------------------------------------------------- | ----------------------------- |
| [Example Configs](../examples/configs/README.md)                                    | All pre-made configurations   |
| [Practical Guide Examples](PRACTICAL_GUIDE.md#real-world-examples-explained-simply) | Detailed example explanations |

### **Contributing**

| Document                                        | Purpose                 |
| ----------------------------------------------- | ----------------------- |
| [CONTRIBUTING.md](../CONTRIBUTING.md)           | How to contribute       |
| [Implementation Notes](IMPLEMENTATION_NOTES.md) | Understand the codebase |
| [Testing Guide](../TESTING.md)                  | How to run tests        |

---

## 🗺️ **Documentation Roadmap**

### **If you're brand new:**

```
1. Practical Guide (understand the tool)
   ↓
2. Try examples (see it in action)
   ↓
3. JSON Guide (configure your problem)
   ↓
4. README (deeper technical details)
```

### **If you want to use Python API:**

```
1. Quick Start Guide
   ↓
2. README API Reference
   ↓
3. Implementation Notes (optional)
```

### **If you want to understand the math:**

```
1. Algorithm Walkthrough
   ↓
2. Verification Tests
   ↓
3. Implementation Notes
```

---

## 📄 **All Documents**

### **Main Documentation**

- **[QUICKSTART.md](../QUICKSTART.md)** - Installation and first run (canonical)
- **[README.md](../README.md)** - Main library documentation, API reference, CLI reference
- **[PRACTICAL_GUIDE.md](PRACTICAL_GUIDE.md)** - When/how to use this tool (comprehensive guide) ⭐
- **[JSON_GUIDE.md](JSON_GUIDE.md)** - General-purpose MDP JSON format
- **[WALKTHROUGH.md](WALKTHROUGH.md)** - Algorithm explanation
- **[IMPLEMENTATION_NOTES.md](IMPLEMENTATION_NOTES.md)** - Project summary, design decisions

### **Testing & Verification**

- **[TESTING.md](../TESTING.md)** - How to run tests
- **[VERIFICATION.md](../tests/VERIFICATION.md)** - Algorithm verification

### **Examples**

- **[examples/configs/README.md](../examples/configs/README.md)** - All example configurations

### **Contributing**

- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines

---

## 💡 **Quick Reference**

**"I want to install and run"**  
→ [QUICKSTART](../QUICKSTART.md)

**"I want to know if this tool can help me"**  
→ [Practical Guide](PRACTICAL_GUIDE.md)

**"I need to configure my problem"**  
→ [JSON Guide](JSON_GUIDE.md)

**"I want to use the Python API"**  
→ [README API Reference](../README.md#api-reference)

**"I want to understand the algorithm"**  
→ [Algorithm Walkthrough](WALKTHROUGH.md)

**"I want to see examples"**  
→ [Example Configs](../examples/configs/README.md)

**"I want to verify it works"**  
→ [Verification Tests](../tests/VERIFICATION.md)

**"I want to contribute"**  
→ [Contributing Guide](../CONTRIBUTING.md)

---

## 🔄 **Keep Updated**

Documentation is actively maintained. If you find:

- ❌ Outdated information
- ❌ Broken links
- ❌ Unclear explanations
- ✅ Suggestions for improvement

Please open an issue or submit a PR!

---

**Last Updated**: January 2026
