How Finance Teams Document Quantitative Models in Confluence

Most quantitative model documentation is a mess — not because quants don't care about documentation, but because the tools for writing math and the tools for sharing knowledge with a team don't overlap.

The model lives in Python or R. The derivations live in a LaTeX PDF that took three days to write and is now orphaned in a shared drive folder nobody navigates. The assumptions are in a Word document last edited in 2023. The backtesting results are in Excel. A new analyst joining the team has to reconstruct the model's intent by reading code comments and asking questions.

Confluence is where team knowledge should live. But until recently, Confluence had no good way to write actual math — which meant quant teams had the choice between prose approximations that lose precision, or screenshots of equations that become wrong the moment the model changes.

---

What Quantitative Model Documentation Should Include

Good model documentation isn't just the formula. It's the context that makes the formula meaningful to someone who didn't build it.

Model purpose and scope — what decision this model informs, what asset class or portfolio it applies to, and what it explicitly does not cover. This section is often skipped and is often the most important.

Assumptions — every model has them. Write them down explicitly. Which distributional assumptions are you making? What market conditions does the model assume? Where does it break down?

Formula derivation — the derivation from first principles, or a clear reference to where that derivation lives. Not just the final formula, but why it takes that form.

Input and output specification — what goes in, what comes out, what units, what frequency, what data sources. A table is cleaner than prose here.

Backtesting and validation results — summary statistics, time period, benchmark comparison. These change as you re-run validation; note the date.

Limitations and known failure modes — where the model underperforms, what conditions make it unreliable, what it should not be used for. This is the section that protects the team.

Version and change history — when the model was last updated, what changed, and why.

---

Writing Formulas in Confluence with LaTeX

LaTeX Math for Confluence adds a /latex macro to Confluence that renders LaTeX equations live on the page. Type the macro, write the LaTeX source, and the rendered equation appears — inline or as a block. No screenshots, no external editors, no export-and-upload cycle.

Here's what real quant model documentation looks like with it.

---

Option Pricing: Black-Scholes

The Black-Scholes formula for a European call option:

C = S_0 \, N(d_1) - K e^{-rT} N(d_2)

Where:

d_1 = \frac{\ln(S_0 / K) + (r + \tfrac{1}{2}\sigma^2)T}{\sigma\sqrt{T}}
\qquad
d_2 = d_1 - \sigma\sqrt{T}

And $N(\cdot)$ is the standard normal CDF. Documenting the variable definitions inline is straightforward — you can mix inline LaTeX like $S_0$ (current price), $K$ (strike), $r$ (risk-free rate), $\sigma$ (volatility), $T$ (time to expiry) into a paragraph without switching formats.

---

Portfolio Risk: Variance and Volatility

Portfolio variance for a two-asset portfolio:

\sigma_p^2 = w_1^2 \sigma_1^2 + w_2^2 \sigma_2^2 + 2 w_1 w_2 \sigma_1 \sigma_2 \rho_{12}

Generalised to $n$ assets using the covariance matrix $\Sigma$:

\sigma_p^2 = \mathbf{w}^\top \Sigma \, \mathbf{w}

Where $\mathbf{w}$ is the vector of portfolio weights. This is the kind of expression that, written in plain text, requires three sentences to explain what a single line of math conveys unambiguously.

---

Performance Metrics: Sharpe and Sortino Ratios

Sharpe ratio:

S = \frac{\mathbb{E}[R_p - R_f]}{\sigma_p}

Sortino ratio, which penalises only downside volatility:

\text{Sortino} = \frac{\mathbb{E}[R_p - R_f]}{\sigma_d}
\qquad
\sigma_d = \sqrt{\mathbb{E}\left[\min(R_p - R_f,\, 0)^2\right]}

Documenting both on the same page with their formulas makes clear why you might prefer one over the other for a strategy with asymmetric return distributions — which is precisely the kind of reasoning that should be captured in model documentation.

---

Risk Models: Value at Risk

Parametric VaR at confidence level $\alpha$:

\text{VaR}_\alpha = \mu_p - z_\alpha \, \sigma_p

Historical simulation VaR — defined as the $(1-\alpha)$ quantile of the empirical return distribution ${r_t}_{t=1}^T$:

\text{VaR}_\alpha = -Q_{1-\alpha}\left(\{r_t\}\right)

Conditional VaR (Expected Shortfall):

\text{CVaR}_\alpha = -\mathbb{E}\left[R \mid R \leq -\text{VaR}_\alpha\right]

These three measures are often discussed together but have meaningfully different properties in tail events. Having all three on one page with their exact definitions eliminates the ambiguity that shows up in verbal descriptions.

---

Fixed Income: Duration and Convexity

Modified duration:

D_{mod} = -\frac{1}{P} \frac{dP}{dy} = \frac{D_{mac}}{1 + y/m}

Where $D_{mac}$ is Macaulay duration, $y$ is yield to maturity, and $m$ is the number of coupon periods per year.

Convexity:

C = \frac{1}{P} \frac{d^2P}{dy^2}

Price change approximation incorporating both:

\frac{\Delta P}{P} \approx -D_{mod} \cdot \Delta y + \frac{1}{2} C \cdot (\Delta y)^2

---

Structuring a Model Documentation Page in Confluence

A consistent page template makes model docs easier to write and easier to audit. Here's a structure that works:

Model: [Model Name]
├── 1. Overview
│   ├── Purpose
│   ├── Scope and applicable instruments
│   └── Owner and last review date
├── 2. Assumptions
│   └── Numbered list — be specific
├── 3. Model Specification
│   ├── Notation table (define every symbol)
│   ├── Derivation (or reference)
│   └── Final formula(s) as block equations
├── 4. Inputs and Outputs
│   └── Table: variable, type, source, frequency
├── 5. Implementation Notes
│   ├── Code reference (link to repo/file)
│   └── Numerical considerations (overflow, precision)
├── 6. Validation and Backtesting
│   ├── Methodology
│   ├── Time period
│   └── Results summary (table)
├── 7. Limitations
│   └── Explicit failure modes
└── 8. Change Log
    └── Date | Change | Author

The notation table in section 3 is often skipped and almost always needed. Every symbol used in the formulas should appear in a table with its definition, units, and typical range. A reader who wasn't in the original modelling sessions shouldn't have to guess what $\lambda$ refers to.

---

Keeping Model Documentation Up to Date

Model documentation drifts for the same reason all documentation drifts: updating it is a separate step from updating the model.

A few practices that help:

Treat the Confluence page as part of the model. Link to it from the code repository — a comment in the main model file pointing to the Confluence page URL. When a developer opens the file to make changes, the docs link is visible.

Add a documentation review step to your model validation process. Most quant teams already have a formal model validation workflow. Add a checkpoint: has the Confluence page been updated to match the current implementation?

Use the change log section. It doesn't need to be exhaustive — a one-line entry per model update (date, what changed, who changed it) is enough to give future readers context. This is much cheaper to maintain than reconstructing history from git blame.

Keep equations as LaTeX source, not images. The point of using LaTeX Math for Confluence is that the source is editable in place. When a formula changes, you edit the LaTeX directly on the Confluence page — two minutes of work, not an export-and-upload cycle. That lower friction is what makes it realistic to keep docs in sync.

---

Getting Started

Install LaTeX Math for Confluence from the Atlassian Marketplace. On any Confluence page, type /latex to insert a block equation or use the inline variant for in-paragraph math.

Full documentation is at LaTeX Math for Confluence docs.

---

Questions? Reach out via our support portal.