PickleBALLER/docs/README.md

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):

brew install mactex

Then compile:

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

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

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:

   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:

@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 ✅