DEV Community

Cover image for How Data Science Teams Document ML Models in Confluence
Yamuno Software profile image Yamuno
Yamuno for Yamuno Software

Posted on • Originally published at yamuno.com

How Data Science Teams Document ML Models in Confluence

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 are using it to actually document their models.

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 or /math on any Confluence page and get a live editor. Equations render in real time as you type, and you can choose inline (within a sentence) or block (standalone, centered) layout.

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})
Enter fullscreen mode Exit fullscreen mode

Mean squared error:

\mathcal{L}_{MSE} = \frac{1}{N} \sum_{i=1}^{N} (y_i - \hat{y}_i)^2
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Sigmoid:

\sigma(x) = \frac{1}{1 + e^{-x}}
Enter fullscreen mode Exit fullscreen mode

Softmax (for a vector z of length K):

\text{softmax}(z_j) = \frac{e^{z_j}}{\sum_{k=1}^{K} e^{z_k}}
Enter fullscreen mode Exit fullscreen mode

GELU (common in transformer models):

\text{GELU}(x) = x \cdot \Phi(x)
Enter fullscreen mode Exit fullscreen mode

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}
Enter fullscreen mode Exit fullscreen mode

F1 score:

F_1 = 2 \cdot \frac{\text{Precision} \cdot \text{Recall}}{\text{Precision} + \text{Recall}}
Enter fullscreen mode Exit fullscreen mode

AUROC is harder to describe in words than in math:

\text{AUROC} = \int_0^1 \text{TPR}(t) \, d(\text{FPR}(t))
Enter fullscreen mode Exit fullscreen mode

Regularisation and Optimisers

L2 regularisation added to a loss term:

\mathcal{L}_{reg} = \mathcal{L} + \lambda \sum_{j} w_j^2
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
\hat{m}_t = \frac{m_t}{1 - \beta_1^t}
\qquad
\hat{v}_t = \frac{v_t}{1 - \beta_2^t}
Enter fullscreen mode Exit fullscreen mode 
\theta_{t+1} = \theta_t - \frac{\eta}{\sqrt{\hat{v}_t} + \epsilon} \hat{m}_t
Enter fullscreen mode Exit fullscreen mode

Bayesian and Probabilistic Models

Teams doing probabilistic modelling or Bayesian inference often have the worst documentation problem — Bayes' theorem in a Slack message is a disaster. In Confluence it's clean:

P(\theta \mid X) = \frac{P(X \mid \theta) \, P(\theta)}{P(X)}
Enter fullscreen mode Exit fullscreen mode

KL divergence between two distributions:

D_{KL}(P \| Q) = \sum_{x} P(x) \log \frac{P(x)}{Q(x)}
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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 to insert a block equation or /math for an inline equation.

Full documentation is at LaTeX Math for Confluence docs.

Questions? Reach out via our support portal.

Top comments (0)