Engineering Use Cases

Overview

This page shows real-world documentation scenarios where LaTeX Formulas & Diagrams adds the most value for engineering and technical teams. Each use case includes the relevant diagram or formula type, the scenario context, and a ready-to-use example.

---

Use Case 1: SLA Documentation with Formulas

Scenario: Your team documents service-level agreements and needs to show the availability and MTTR formulas alongside target values.

Macro: LaTeX Block

Example - Three Nines SLA:

\text{Availability} = \frac{\text{MTBF}}{\text{MTBF} + \text{MTTR}} = 99.9\%

\text{Monthly downtime allowance} = 0.001 \times 30 \times 24 \times 60 \approx 43.2 \text{ minutes}

How to structure the page:

1. Use a Confluence table for target vs. actual SLA values
2. Embed LaTeX Block macros inline to show the mathematical definitions
3. Use a UML Diagrams (Flowchart) macro to show the incident escalation path

---

Use Case 2: Database Schema with ERD

Scenario: Your team is documenting the data model for a new microservice and wants an always-current ERD directly on the Confluence spec page.

Macro: UML Diagrams → erDiagram

Example - E-commerce Order Service:

erDiagram
  CUSTOMER {
    int id PK
    string email
    string name
    date created_at
  }
  ORDER {
    int id PK
    int customer_id FK
    decimal total
    string status
    date placed_at
  }
  ORDER_ITEM {
    int id PK
    int order_id FK
    int product_id FK
    int quantity
    decimal unit_price
  }
  PRODUCT {
    int id PK
    string sku
    string name
    decimal price
  }
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : "is in"

Why this beats a screenshot: The Mermaid source is editable directly on the Confluence page - no need to update an image file when the schema changes.

---

Use Case 3: API Sequence Diagram in Technical Specs

Scenario: Documenting an OAuth 2.0 authorization code flow for a new integration in an Architecture Decision Record (ADR).

Macro: UML Diagrams → sequenceDiagram

Example:

sequenceDiagram
  participant User as Browser
  participant App as Application
  participant Auth as Auth Server
  participant API as Resource API

  User->>App: Click "Login with OAuth"
  App->>Auth: Redirect with client_id + scope
  User->>Auth: Enter credentials + consent
  Auth-->>App: Authorization code (redirect)
  App->>Auth: POST /token with code + secret
  Auth-->>App: Access token + refresh token
  App->>API: GET /data with Bearer token
  API-->>App: Protected resource
  App-->>User: Render data

---

Use Case 4: Machine Learning Model Documentation

Scenario: A data science team documents a model's loss function and accuracy metrics in a model card on Confluence.

Macro: LaTeX Block (for formulas) + LaTeX Inline (for in-text references)

Block formulas:

\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]

\text{F1} = 2 \cdot \frac{\text{Precision} \times \text{Recall}}{\text{Precision} + \text{Recall}}

Inline formula example (inside a sentence):

Write this in a paragraph macro:

"The model achieves \text{Accuracy} = \frac{TP+TN}{TP+TN+FP+FN} = 94.3% on the held-out test set."

---

Use Case 5: CI/CD Pipeline Flowchart

Scenario: Documenting your deployment pipeline in the engineering runbook so new team members can understand the end-to-end flow.

Macro: UML Diagrams → flowchart LR

Example:

flowchart LR
  A[Developer Push] --> B[GitHub Actions Trigger]
  B --> C[Lint & Unit Tests]
  C --> D{Tests Pass?}
  D -- No --> E[Notify Developer]
  D -- Yes --> F[Build Docker Image]
  F --> G[Push to ECR]
  G --> H[Deploy to Staging]
  H --> I[Smoke Tests]
  I --> J{Smoke Tests Pass?}
  J -- No --> K[Rollback Staging]
  J -- Yes --> L[Manual Approval]
  L --> M[Deploy to Production]
  M --> N[Post-Deploy Monitoring]

---

Use Case 6: Sprint Gantt Chart in Retrospective Pages

Scenario: Embedding a Gantt chart in a sprint planning or retrospective page to visualize task breakdown and timeline.

Macro: UML Diagrams → gantt

Example:

gantt
  title Sprint 42 - Feature: Payments Module
  dateFormat YYYY-MM-DD
  section Backend
  Payment API design     :done, 2024-03-01, 2024-03-04
  Stripe integration     :active, 2024-03-04, 2024-03-11
  Webhook handler        :2024-03-11, 2024-03-15
  section Frontend
  Payment form UI        :2024-03-06, 2024-03-12
  3DS confirmation modal :2024-03-12, 2024-03-15
  section QA
  Integration tests      :2024-03-15, 2024-03-20
  Staging validation     :milestone, 2024-03-20, 1d

---

Tips for Engineering Teams