Writing Technical Documentation with Code Blocks, Mermaid, and LaTeX

TL;DR: High-impact technical documentation bridges code, architecture, and mathematical rigor. Text alone fails to describe distributed state machines or algorithmic bounds. By combining syntax-highlighted code blocks, Mermaid text-based diagrams, and LaTeX math formulas, you build documentation that is version-controlled, diffable, and clear. Learn the patterns, real-world examples, and how modern developer platforms like ZyVOP render and distribute this rich triad without friction.

The Triad of Modern Technical Documentation

Software engineering documentation often suffers from two extremes:

Wall-of-text fatigue: Thousands of words describing asynchronous handshakes and database locks that nobody reads or remembers.
Stale binary sprawl: Cloud architecture diagrams exported from proprietary drag-and-drop tools as .png files, buried in wiki pages and obsolete within two sprints.

When engineers explain complex systems face-to-face, they naturally do three things: write code snippets, sketch boxes and arrows on a whiteboard, and scribble formulas for rates, SLAs, or complexity.

Modern technical documentation should mirror that exact behavior using plain text:

flowchart TD
    subgraph Triad ["The Technical Documentation Triad"]
        direction LR
        Code["Code Blocks<br/>(Syntax, Types & Logic)"]
        Diagram["Mermaid.js<br/>(Architecture & Flows)"]
        Math["LaTeX / KaTeX<br/>(Formulas, Proofs & SLAs)"]
    end
    Code & Diagram & Math --> Spec(["Living Technical Spec"])

When all three live directly in Markdown, your documentation stays alongside your code in Git, passes CI checks, and diffs cleanly in pull requests.

1. Code Blocks: Beyond Generic Syntax Fences

A code snippet in documentation is not just an illustration—it is a verifiable contract.

Best Practices for Technical Code Blocks

Always declare the language tag: Use accurate identifiers (typescript, python, rust, json, bash) so parsers invoke correct tokenizers.
Isolate the core concept: Eliminate boilerplate imports and scaffolding unless teaching initialization. Focus directly on the critical logic.
Include type annotations & invariants: Types communicate intent faster than descriptive prose.

Example: Atomic Sliding-Window Rate Limiter

Here is how an atomic Redis sliding-window check should look in production documentation:

import type { Redis } from 'ioredis';

interface RateLimitResult {
  allowed: boolean;
  remaining: number;
  resetMs: number;
}

export async function checkSlidingWindow(
  redis: Redis,
  identifier: string,
  limit: number,
  windowMs: number
): Promise<RateLimitResult> {
  const now = Date.now();
  const windowStart = now - windowMs;
  const key = `ratelimit:${identifier}`;

  // Execute sliding window log atomically via Redis transaction
  const [_, logCount] = await redis
    .multi()
    .zremrangebyscore(key, 0, windowStart) // Evict stale timestamps
    .zcard(key)                            // Count current requests
    .exec() as [unknown, [Error | null, number]];

  const currentRequests = logCount[1] ?? 0;
  if (currentRequests >= limit) {
    return { allowed: false, remaining: 0, resetMs: windowMs };
  }

  await redis.zadd(key, now, `${now}-${Math.random()}`);
  await redis.pexpire(key, windowMs);

  return {
    allowed: true,
    remaining: Math.max(0, limit - currentRequests - 1),
    resetMs: windowMs,
  };
}

2. Mermaid.js: Architecture and Flow as Code

Static images are the enemy of durable technical documentation. The moment a service endpoint or retry condition changes, updating an exported PNG requires finding the original canvas file, re-exporting, and committing a multi-megabyte binary.

Mermaid.js solves this by compiling declarative text definitions directly into SVG diagrams within Markdown.

Why Text-Based Diagrams Win

Diffable in Pull Requests: Teammates review diagram changes in the same PR review pane as backend code.
Zero tooling overhead: Anyone with a text editor can adjust a flow.
Searchable: Diagram node labels and edge descriptions are indexed by full-text search engines.

Example: Sequence Flow with Error Recovery

Consider an event-driven payment and webhook distribution pipeline:

sequenceDiagram
    autonumber
    actor Client
    participant Gateway as API Gateway
    participant Auth as Auth / Vault
    participant Queue as Redis Stream / BullMQ
    participant Worker as Syndication Worker

    Client->>Gateway: POST /v1/articles/publish
    Gateway->>Auth: Validate Token & Signing Key
    alt Invalid Key
        Auth-->>Gateway: 401 Unauthorized
        Gateway-->>Client: 401 Error Payload
    else Valid Credentials
        Auth-->>Gateway: 200 OK (Author Context)
        Gateway->>Queue: Push Job: { articleId, targets }
        Queue-->>Gateway: Job Enqueued (job_8492)
        Gateway-->>Client: 202 Accepted (jobId)
        
        loop Retries with Backoff
            Queue->>Worker: Dispatch Job
            Worker->>Worker: Transform Markdown & Render Diagrams
            alt Downstream Flake (502 / Timeout)
                Worker-->>Queue: Retry with exponential backoff
            else Success
                Worker-->>Queue: Mark Job Completed
            end
        end
    end

State Diagrams for Life Cycles

Mermaid is equally effective for representing entity life cycles and circuit breaker states:

stateDiagram-v2
    [*] --> Draft : Author creates post
    Draft --> InReview : Submit for verification
    InReview --> Scheduled : Approved with release date
    InReview --> Draft : Revisions requested
    Scheduled --> Published : Cron trigger fires
    Published --> Syndicated : Cross-posted to targets
    Published --> Archived : Deprecated by author

3. LaTeX: Precision for Algorithms, SLOs, and Metrics

When describing performance, cost modeling, distributed consensus, or mathematical boundaries, prose easily becomes ambiguous. Writing O(n log n) in unformatted plaintext is tolerable, but calculating backoff intervals, token bucket replenishment, or cache efficiency quickly degrades without mathematical typesetting.

Modern Markdown engines use LaTeX / KaTeX notation:

Inline math wrapped in single dollar signs: $E = mc^2$
Display / Block math wrapped in double dollar signs: $$\sum_{i=1}^n i$$

Example 1: Token Bucket Replenishment Formula

To explain how a rate limiter recalculates available tokens on the fly without running background timers:

The token balance $B(t)$ at arrival timestamp $t$ given previous check $t_0$, capacity $C$, and refill rate $\rho$ (tokens/sec) is expressed as:

$$B(t) = \min\left(C, ; B(t_0) + \rho \cdot (t - t_0)\right)$$

If an incoming operation costs $k$ tokens, the operation is permitted if and only if:

$$B(t) \ge k \quad \implies \quad B_{\text{new}}(t) = B(t) - k$$

Example 2: Distributed Latency & SLA Percentiles

When writing an RFC on service-level objectives, aggregate user-perceived latency across $m$ parallel sub-requests can be formally documented:

$$P(\text{All sub-requests} \le L) = \prod_{i=1}^{m} F_i(L) = \left[ F(L) \right]^m$$

Even if individual services boast a 99th percentile latency ($F(L) = 0.99$), an endpoint querying $m = 10$ dependencies experiences a joint success rate of:

$$P(\text{Success}) = 0.99^{10} \approx 0.904$$

This yields an aggregate success rate of only ~90.4% despite 99% component availability. Documenting this mathematically prevents unrealistic architectural assumptions before code is written.

Putting It Together: A Complete Micro-Spec

Let's look at how combining code, Mermaid, and LaTeX creates an unambiguous mini-spec for an Exponential Backoff with Jitter retry handler:

1. Mathematical Definition

We use full jitter to prevent thundering herd spikes on downstream API endpoints:

$$t_{\text{wait}} = \text{random}(0, ; \min(M, ; B \cdot 2^{\text{attempt}}))$$

Where:

$B$ is the base retry duration (e.g., $100,\text{ms}$)
$M$ is the maximum backoff ceiling (e.g., $10{,}000,\text{ms}$)
$\text{attempt} \in [0, \text{max_retries}]$

2. Execution Flow (Mermaid)

flowchart TD
    Start(["Execute Request"]) --> Check{"Success?"}
    Check -- Yes --> Return(["Return Response"])
    Check -- "No (5xx / Network)" --> Attempts{"Attempt < Max?"}
    Attempts -- No --> Throw(["Throw MaxRetriesExceeded"])
    Attempts -- Yes --> Calc["Compute Backoff: t = random(0, min(M, B * 2^attempt))"]
    Calc --> Sleep["Sleep for t milliseconds"]
    Sleep --> Start

3. Implementation (TypeScript)

export async function withExponentialBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 5,
  baseMs = 100,
  maxMs = 10000
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      const ceiling = Math.min(maxMs, baseMs * Math.pow(2, attempt));
      const jitterDelay = Math.floor(Math.random() * ceiling);
      await new Promise((res) => setTimeout(res, jitterDelay));
    }
  }
  throw new Error('Unreachable retry state');
}

The Distribution Challenge: Where Most Tooling Breaks

Writing rich technical Markdown in your favorite editor is satisfying, but publishing it is where friction begins:

GitHub / GitLab render Mermaid and LaTeX natively in READMEs, but they are not built for public reader engagement or subscriber distribution.
Dev.to, Hashnode, Medium, and WordPress have fragmented support: some strip LaTeX equations, others garble Mermaid blocks into unrendered text, and Medium lacks native code syntax trees for modern languages.
Manual rework: Writers often resort to taking screenshot cutouts of diagrams or embedding formulas as images, losing responsiveness and dark-mode styling.

How ZyVOP Streamlines Rich Technical Authoring

This is where ZyVOP provides an ideal home for technical authors and engineering teams.

Designed as an author-owned Developer Publishing Hub, ZyVOP treats technical notation as first-class citizens:

Native Triad Rendering: ZyVOP's Tiptap-powered editor and reading experience natively render syntax-highlighted code across dozens of languages, live interactive Mermaid diagrams, and KaTeX mathematical notation.
GitOps & CLI Workflow: With npx zyvop, engineers write Markdown and diagrams inside their standard Git repositories alongside unit tests, validating docs through CI and publishing idempotently using frontmatter metadata.
Cross-Platform Syndication with Zero Loss: When cross-posting to external platforms (Dev.to, Hashnode, Medium, WordPress), ZyVOP automatically handles platform-specific formatting while preserving your canonical URL and SEO authority.

flowchart TD
    Git["Git Repository<br/>(Markdown + Specs)"]
    Hub["ZyVOP Canonical Author Hub<br/>(Mermaid SVGs • KaTeX Formulas • Dark Mode)"]

    Git -- "npx zyvop publish" --> Hub
    Hub --> Dev["Dev.to<br/>(Formatted)"]
    Hub --> Hashnode["Hashnode<br/>(Formatted)"]
    Hub --> Medium["Medium<br/>(Preserved)"]

4 Rules for High-Integrity Technical Docs

Keep Diagrams Under 15 Nodes: If a Mermaid chart scrolls off-screen or requires zooming to read, decompose it into subgraphs or sequential views.
Always Define Formula Variables: Never output a LaTeX equation without listing every variable and its operational units (milliseconds, bytes, queries/sec).
Make Code Snippets Standalone: Ensure every snippet has clear inputs, return types, and expected side effects.
Preserve Canonical Ownership: Don't let your best architectural writing get locked into single-vendor platforms. Keep source documents in Git and publish through platforms that respect canonical ownership.

Conclusion

Technical documentation is engineering communication at its highest leverage. By uniting executable code blocks, declarative Mermaid diagrams, and rigorous LaTeX mathematics, you turn static documentation into a dynamic, version-controlled source of truth.

Start writing with this triad in your next RFC, architecture guide, or engineering post—and let platforms like ZyVOP handle the heavy lifting of previewing, versioning, and distributing your work to the developer world.