# Pickleball Rating System Documentation

This directory contains the technical documentation for the Pickleball ELO Tracker, specifically the redesign from v1.0 to v2.0.

## Files

### `rating-system-v2.tex`
**The main technical report** documenting the complete redesign of the rating system.

**Contents:**
- **Title:** "Pickleball Rating System v2.0: A Principled Approach to Doubles Ranking"
- **Authors:** Split (Implementation), Dane Sabo (System Design)
- **Length:** ~680 lines, ~9,000 words
- **Sections:**
  1. TL;DR summary box
  2. Introduction (context and overview)
  3. Glicko-2 fundamentals (mathematical foundation)
  4. System v1.0 (the previous approach and its issues)
  5. Motivation for changes (4 key problems identified)
  6. System v2.0 (new formulas and philosophy)
  7. Complete formulas for v2.0
  8. Example calculation (concrete doubles match walkthrough)
  9. Discussion (advantages, edge cases, future work)
  10. References

**Mathematical Content:**
- Includes all formulas in clear mathematical notation
- Per-point expected value model with derivations
- Effective opponent formula with intuitive explanations
- Complete RD distribution fix
- Comparison tables between v1 and v2

**Technical Depth:**
- Accessible to recreational players (no prior rating knowledge assumed)
- Conversational but precise
- Suitable for blog post/website publication
- Includes worked examples with real numbers

## Compiling the Document

The `rating-system-v2.tex` file is in standard LaTeX format and requires a TeX installation to compile to PDF.

### On macOS
Install MacTeX (includes pdflatex):
```bash
brew install mactex
```

Then compile:
```bash
cd /Users/split/Projects/pickleball-elo/docs
pdflatex rating-system-v2.tex
pdflatex rating-system-v2.tex  # Run twice for TOC/references
```

This generates `rating-system-v2.pdf`.

### On Linux
```bash
sudo apt install texlive-latex-base texlive-latex-extra
cd docs
pdflatex rating-system-v2.tex
pdflatex rating-system-v2.tex
```

### Using Overleaf (Online)
1. Go to https://www.overleaf.com
2. Create new project → Upload project
3. Upload `rating-system-v2.tex`
4. Click "Recompile" to generate PDF

### Using Docker
```bash
docker run --rm -v $(pwd):/data -w /data texlive/texlive:latest \
  pdflatex rating-system-v2.tex
```

## Document Features

### TL;DR Box
At the very beginning is a highlighted box summarizing the four main changes in plain language:
- Scoring method change
- RD distribution fix
- Effective opponent formula
- Unified rating plan

Perfect for readers who just want the executive summary.

### Mathematical Formulas
All formulas are typeset using `amsmath` with clear variable definitions:
- Per-point expected value: `P(win) = 1 / (1 + 10^((R_opp - R_self)/400))`
- Performance ratio: `Points Scored / Total Points`
- Effective opponent: `R_eff = R_opp1 + R_opp2 - R_teammate`
- RD distribution (fixed): `w_i = d_i^2` (not `1/d_i^2`)

### Worked Example
Section 7 walks through a complete doubles match (Alice & Bob vs Carol & Dave) showing:
- How the old system calculated the match outcome
- How the new system calculates it
- Side-by-side comparison of rating changes
- Explanation of why each player's update changed

### Discussion Section
Covers:
- Advantages of the new system
- Potential edge cases and how they're handled
- Future improvements (unified ratings, time decay, location adjustments, volatility calibration)

## Publishing to Website

The document is suitable for blog publication:
1. **Print to HTML** using Pandoc:
   ```bash
   pandoc rating-system-v2.tex -o rating-system-v2.html --mathjax
   ```
   
2. **Extract key sections** for a blog post (Introduction + Motivation + Example)

3. **Embed in GitHub/website** (GitHub renders LaTeX formulas in markdown)

## Citation Format

For academic reference:
```bibtex
@techreport{pickleball_elo_v2,
  title = {Pickleball Rating System v2.0: A Principled Approach to Doubles Ranking},
  author = {Split and Dane Sabo},
  year = {2026},
  month = {February},
  organization = {Pickleball ELO Tracker}
}
```

## Questions/Feedback

For technical questions about the rating system, refer to:
- **Code:** `/Users/split/Projects/pickleball-elo/src/glicko/`
- **REFACTORING_NOTES.md:** Implementation details and migration plan
- **COMPLETION_SUMMARY.md:** Quick summary of all changes

---

**Document Version:** 1.0
**Last Updated:** February 26, 2026
**Status:** Ready for publication ✅