Common Use Cases
Real-world scenarios where teams use LaTeX Formulas & Diagrams in Confluence. Each scenario includes who it's for, when to use it, which macro to use, and an example.
1. Architecture Decision Record (ADR) with System Diagram
Who: Software engineers, architects, tech leads
When: Documenting a new system design decision that requires a visual of how components interact
Macro to use: UML Diagrams - sequence or component diagram
Why it works: ADRs need precise, readable diagrams that can be version-controlled alongside the decision text. Mermaid code is stored in page history, so the diagram evolves with the decision.
Example - Sequence Diagram for a Microservice Call:
sequenceDiagram
participant Client as API Client
participant Gateway as API Gateway
participant Auth as Auth Service
participant Orders as Orders Service
participant DB as Orders DB
Client->>Gateway: POST /orders { items, userId }
Gateway->>Auth: Validate JWT token
activate Auth
Auth-->>Gateway: 200 OK { userId, roles }
deactivate Auth
Gateway->>Orders: Create order { items, userId }
activate Orders
Orders->>DB: INSERT INTO orders ...
activate DB
DB-->>Orders: order_id = 4821
deactivate DB
Orders-->>Gateway: 201 Created { orderId: 4821 }
deactivate Orders
Gateway-->>Client: 201 Created { orderId: 4821 }
2. Data Science Documentation with Formulas
Who: Data scientists, ML engineers, analysts
When: Documenting a model's loss function, evaluation metrics, or mathematical derivation in a team wiki or model card
Macro to use: LaTeX Block Equations for standalone formulas; LaTeX Inline Equations for formulas embedded in explanatory text
Why it works: LaTeX is the standard notation for mathematical publishing. The app renders it natively in Confluence, so data science docs look as precise as academic papers.
Example - Model Evaluation Metrics (LaTeX Block):
\begin{aligned}
\text{Precision} &= \frac{TP}{TP + FP} \\[6pt]
\text{Recall} &= \frac{TP}{TP + FN} \\[6pt]
F_1 &= 2 \cdot \frac{\text{Precision} \cdot \text{Recall}}{\text{Precision} + \text{Recall}} \\[6pt]
\text{RMSE} &= \sqrt{\frac{1}{n}\sum_{i=1}^{n}(y_i - \hat{y}_i)^2}
\end{aligned}
Example - Inline math in a paragraph (LaTeX Inline):
The model minimizes the cross-entropy loss L = -\sum_{i} y_i \log(\hat{y}_i) over the training set, where y_i is the true label and \hat{y}_i is the predicted probability.
3. Project Timeline with Gantt Chart
Who: Project managers, engineering managers, program managers
When: Planning a sprint, quarter, or release cycle and sharing the timeline with the team in Confluence
Macro to use: UML Diagrams - Gantt chart
Why it works: Gantt charts defined in Mermaid are easy to update (just change dates in text), live in Confluence page history, and require no external tools or image uploads.
Example - Q2 Release Timeline:
gantt
title Q2 2024 Release Timeline
dateFormat YYYY-MM-DD
section Discovery
Requirements Gathering :done, req, 2024-04-01, 2024-04-10
Stakeholder Review :done, review, 2024-04-10, 2024-04-15
section Development
Backend API :active, api, 2024-04-15, 2024-05-15
Frontend UI :ui, 2024-04-22, 2024-05-20
section QA & Testing
Integration Testing :test, 2024-05-15, 2024-06-01
UAT :uat, 2024-06-01, 2024-06-10
section Release
Staging Deployment :staging, 2024-06-10, 2024-06-12
Production Release :milestone, prod, 2024-06-14, 1d
4. Database Schema Documentation
Who: Backend engineers, database administrators, data engineers
When: Documenting a database schema for a new feature, onboarding new engineers, or as part of a system design review
Macro to use: UML Diagrams - ERD (Entity Relationship Diagram)
Why it works: ERDs defined in Mermaid are concise, readable, and version-controlled. They update easily when the schema changes - no need to redraw a diagram.
Example - E-Commerce Schema:
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : "included in"
CATEGORY ||--o{ PRODUCT : categorizes
USER {
int id PK
string email UK
string name
timestamp created_at
}
ORDER {
int id PK
int user_id FK
string status
decimal total_amount
timestamp placed_at
}
ORDER_ITEM {
int id PK
int order_id FK
int product_id FK
int quantity
decimal unit_price
}
PRODUCT {
int id PK
int category_id FK
string name
decimal price
int stock_count
}
CATEGORY {
int id PK
string name
string slug
}
5. API Documentation with Sequence Diagrams
Who: API designers, backend engineers, developer experience teams
When: Documenting an API's authentication flow, request lifecycle, or integration pattern for internal or external developers
Macro to use: UML Diagrams - sequence diagram
Why it works: Sequence diagrams precisely show the order of calls, activations, and responses between systems. They are far more readable than prose descriptions of multi-step API flows.
Example - OAuth 2.0 Authorization Code Flow:
sequenceDiagram
participant User as User (Browser)
participant App as Client Application
participant Auth as Authorization Server
participant API as Resource API
User->>App: Click "Sign in with Provider"
App->>Auth: GET /authorize?client_id=...&redirect_uri=...
Auth->>User: Show login & consent screen
User->>Auth: Enter credentials, grant consent
Auth-->>App: Redirect to redirect_uri?code=AUTH_CODE
App->>Auth: POST /token { code, client_id, client_secret }
activate Auth
Auth-->>App: { access_token, refresh_token, expires_in }
deactivate Auth
App->>API: GET /resource Authorization: Bearer access_token
activate API
API-->>App: 200 OK { resource data }
deactivate API
App->>User: Display resource data