Split
4e8c9f53bf
DOCUMENTATION ADDED:
1. docs/rating-system-v2.tex (681 lines, ~9,000 words)
- Complete technical report on system redesign
- Includes: introduction, mathematical foundation, v1 review
- Motivation for all 4 changes with detailed explanations
- Complete v2.0 formulas with clear notation
- Worked example: concrete doubles match (v1 vs v2)
- Discussion of advantages, edge cases, future work
- Professional typesetting for blog/website publication
- 36 subsections with table of contents
2. docs/README.md
- How to compile the LaTeX document
- File overview and contents summary
- Compilation instructions for macOS, Linux, Docker, Overleaf
- Publishing guidance (HTML conversion, blog extraction)
- Citation format for references
3. docs/FORMULAS.md
- Quick reference card for all formulas
- Match outcome calculation (singles & doubles)
- Effective opponent examples
- RD distribution formula with worked examples
- Expected point win probability table
- Parameter meanings and initial values
- Summary of v1 vs v2 changes
- FAQ section
STATUS: Ready for publication ✅
- LaTeX file is syntactically correct
- All formulas verified against code
- Example calculations match implementation
- Suitable for recreational audience + technical rigor
- Can be compiled to PDF or converted to HTML/blog format
146 lines
4.4 KiB
Markdown
146 lines
4.4 KiB
Markdown
# 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 ✅
|