How Data Science Teams Document ML Models in Confluence
Most data science teams have the same documentation problem: the math lives somewhere else.
Loss functions in a Jupyter notebook. Model architecture equations in a Google Doc. Evaluation metrics in a Slack thread. Confluence ends up as a project tracker rather than a real knowledge base, because there was no good way to write math in it.
LaTeX Math for Confluence changes that. Here's how teams use it to document their models. If you have never added an equation to a Confluence page before, start with our guide on how to add math equations to Confluence.
The Problem with Screenshots and Plain Text
The two common workarounds both have obvious failure modes.
Screenshots look fine on day one. Then the model changes, the screenshot is wrong, and nobody updates it because re-exporting from LaTeX or Overleaf and re-uploading feels like too much work. Six months later, the page has equations that don't match the code.
Plain text approximations (loss = -sum(y * log(y_hat))) are readable to the author but lose precision fast. No Greek letters, no proper fractions, no summation notation. Anyone reading the doc has to mentally parse notation that doesn't match what they'd write on a whiteboard.
Documenting Models with LaTeX in Confluence
With LaTeX Math, you type /latex on any Confluence page and pick LaTeX Math for Confluence (Inline) for an equation inside a sentence or LaTeX Math for Confluence (Block) for a standalone, centered equation. The editor shows a live preview as you type, rendered with KaTeX.
Here's how it maps to the kinds of things data science teams actually write.
Loss Functions
The cross-entropy loss for a classification model:
\mathcal{L} = -\frac{1}{N} \sum_{i=1}^{N} \sum_{c=1}^{C} y_{ic} \log(\hat{y}_{ic})
Mean squared error:
\mathcal{L}_{MSE} = \frac{1}{N} \sum_{i=1}^{N} (y_i - \hat{y}_i)^2
Binary cross-entropy:
\mathcal{L} = -\frac{1}{N} \sum_{i=1}^{N} \left[ y_i \log(\hat{y}_i) + (1 - y_i) \log(1 - \hat{y}_i) \right]
These go inline in a model card, in a section right next to the architecture description and training configuration, all in one Confluence page that anyone on the team can find.
Activation Functions
Documenting why you chose a particular activation is easier when you can show it properly.
ReLU:
f(x) = \max(0, x)
Sigmoid:
\sigma(x) = \frac{1}{1 + e^{-x}}
Softmax (for a vector z of length K):
\text{softmax}(z_j) = \frac{e^{z_j}}{\sum_{k=1}^{K} e^{z_k}}
GELU (common in transformer models):
\text{GELU}(x) = x \cdot \Phi(x)
Evaluation Metrics
Precision and recall written in plain text are fine. Written as equations they're unambiguous:
\text{Precision} = \frac{TP}{TP + FP}
\qquad
\text{Recall} = \frac{TP}{TP + FN}
F1 score:
F_1 = 2 \cdot \frac{\text{Precision} \cdot \text{Recall}}{\text{Precision} + \text{Recall}}
AUROC is harder to describe in words than in math:
\text{AUROC} = \int_0^1 \text{TPR}(t) \, d(\text{FPR}(t))
Regularisation and Optimisers
L2 regularisation added to a loss term:
\mathcal{L}_{reg} = \mathcal{L} + \lambda \sum_{j} w_j^2
Adam update rule, the kind of thing that should live in your training runbook:
m_t = \beta_1 m_{t-1} + (1 - \beta_1) g_t
\qquad
v_t = \beta_2 v_{t-1} + (1 - \beta_2) g_t^2
\hat{m}_t = \frac{m_t}{1 - \beta_1^t}
\qquad
\hat{v}_t = \frac{v_t}{1 - \beta_2^t}
\theta_{t+1} = \theta_t - \frac{\eta}{\sqrt{\hat{v}_t} + \epsilon} \hat{m}_t
Bayesian and Probabilistic Models
Teams doing probabilistic modelling or Bayesian inference often have the worst documentation problem. Bayes' theorem in a Slack message is hard to read. In Confluence it's clean:
P(\theta \mid X) = \frac{P(X \mid \theta) \, P(\theta)}{P(X)}
KL divergence between two distributions:
D_{KL}(P \| Q) = \sum_{x} P(x) \log \frac{P(x)}{Q(x)}
ELBO for variational inference:
\mathcal{L}(\phi, \theta) = \mathbb{E}_{q_\phi(z|x)} \left[ \log p_\theta(x|z) \right] - D_{KL}\left( q_\phi(z|x) \| p(z) \right)
What a Model Card Looks Like in Practice
A typical model card in Confluence might be structured like this:
- Overview: what the model does, who it's for
- Architecture: layer counts, attention heads, embedding dimensions (inline equations for shapes)
- Training objective: loss function as a block equation
- Optimiser: learning rate, weight decay, scheduler (formulas inline in a table)
- Evaluation: metrics defined as equations, results as a table
- Known limitations: plain text
With LaTeX Math, the equations in that document are live, editable, and match the actual implementation. When a team member updates the model and changes the loss function, they update the equation directly. No re-exporting, no new screenshots, no broken images.
Getting Started
Install LaTeX Math for Confluence from the Atlassian Marketplace. On any Confluence page, type /latex, then choose LaTeX Math for Confluence (Block) for a standalone equation or LaTeX Math for Confluence (Inline) for an equation inside a sentence.
If you can't remember a command, the LaTeX symbol reference lists the common ones and flags the few that KaTeX does not render. Full documentation is at LaTeX Math for Confluence docs, including the adding macros guide.
Questions? Reach out via our support portal.
