Documentation Authoring Standard

Complete guide to the standards for authoring documentation in the Livepeer documentation repository

Livepeer Documentation Framework & Authoring Standard

Version: 2026 Status: Mandatory Scope: Entire Livepeer Mintlify Repository (docs-v2 and successors)

---

0. Purpose

This document defines the structural, epistemological, mathematical, architectural, and governance standards for all Livepeer documentation.

It establishes:

• The documentation framework model
• The enforcement rules
• The quality bar
• The publication gate criteria

No documentation should be published unless it satisfies this standard.

---

Part I - Documentation Framework Research & Rationale

Livepeer is not a simple developer product. It is:

• A tokenised economic protocol
• A staking network
• An off-chain AI / video execution layer
• A governance system
• A treasury-controlled DAO
• A product platform

No single documentation framework is sufficient.

Below is the evaluated framework stack.

---

1. Diátaxis (Structural Layer)

Purpose: Structural clarity

Diátaxis separates documentation into:

• Tutorials
• How-to Guides
• Reference
• Explanation

Why It Matters

• Prevents mixing instructional and conceptual content
• Prevents tutorials from becoming protocol deep dives
• Creates cognitive clarity
• Scales across large ecosystems

Limitation

Does not enforce economic or protocol rigor.

Adopted Role in Livepeer: Structural classification layer.

Every page must declare its type.

---

2. RFC / Standards Model (Protocol Layer)

Used in:

• IETF
• Ethereum (EIPs)
• Formal governance systems

Strengths

• Normative language (MUST, SHOULD, MAY)
• Formal definitions
• Version clarity
• Technical defensibility
• Upgrade traceability

Limitation

Too rigid for onboarding and UX documentation.

Adopted Role in Livepeer: Protocol, tokenomics, governance, and treasury documentation.

---

3. Ethereum-Style Protocol Documentation

Characteristics:

• Economic modeling
• State transition descriptions
• Contract references
• Governance history
• Upgrade context

Adopted Role in Livepeer: LPT, staking, inflation, treasury, governance logic.

---

4. Stripe / Vercel Model (Product Layer)

Characteristics:

• Developer-first clarity
• Clean UX hierarchy
• Task orientation
• Strong onboarding flow
• Clear architectural explanations

Adopted Role in Livepeer: Gateways, SDKs, APIs, developer workflows.

---

5. Kubernetes / Rust Style (Operational Layer)

Characteristics:

• Explicit architecture diagrams
• Failure modeling
• Operational details
• Clear system boundaries

Adopted Role in Livepeer: Orchestrators, gateways, job routing, network components.

---

Part II - Livepeer Hybrid Documentation Model

Livepeer adopts a layered documentation framework:

Layer	Framework
Structure	Diátaxis
Protocol & Economics	RFC + Ethereum Standard
Product & Developer	Stripe/Vercel Model
Enforcement	Livepeer Authoring Standard

---

Part III - Livepeer Documentation Authoring Standard (2026)

---

1. Foundational Principles

1.1 Verifiability First

All claims must be:

• Traceable to primary sources
• Current as of publication
• Technically defensible

Primary sources include:

• GitHub repositories
• Deployed contracts
• Explorer data
• Governance proposals
• Forum records
• Official announcements
• Recorded demos

If a claim cannot be verified, it must not appear.

Speculation is prohibited unless explicitly labeled.

---

1.2 Protocol vs Network Separation (Mandatory)

Documentation must clearly distinguish:

Protocol (On-Chain / Economic Layer)

• Smart contracts
• Token mechanics
• Inflation functions
• Slashing rules
• Bonding logic
• Governance execution
• Treasury flows

Network (Off-Chain / Operational Layer)

• Node software
• Orchestrator execution
• Gateway routing
• AI pipelines
• Transcoding flows
• Job markets

Cross-layer ambiguity is prohibited.

Each page must explicitly declare which layer it describes.

---

1.3 Documentation Type Declaration (Diátaxis)

Every page must declare:

• Tutorial
• How-to
• Reference
• Explanation

Mixed types are not allowed.

---

2. Mandatory Page Structure

Every documentation page must include:

1. Executive Summary
2. Formal Definition
3. Layer Classification
4. Architectural Context
5. Mechanism-Level Detail
6. Economic / Security Implications (if applicable)
7. Operational Considerations (if applicable)
8. Diagrams (Mermaid required when systems interact)
9. References & Source Links

Depth must serve:

• Protocol researchers
• Production engineers

---

3. Mathematical & Economic Standards

When documenting token economics:

• All variables must be explicitly defined

• Inflation functions must include:

  • Target bonding rate
  • Current bonding rate
  • Adjustment coefficient
  • Update frequency

• Slashing and reward calculations must show derivation

• Yield must separate:

  • Protocol issuance
  • Fee revenue

No formula without defined variables.

---

4. Smart Contract & ABI Requirements

When referencing contracts:

Documentation must include:

• Contract name
• Deployment network
• Verified address
• Verified source link
• ABI reference
• Key callable functions
• Upgradeability notes

All addresses must be verifiable on-chain.

---

5. Metrics Policy

Live network metrics are not mandatory.

However:

• No fabricated values
• No hardcoded dashboard numbers
• Examples must be labeled illustrative
• Prefer derivation methods over volatile values

Constants defined in contracts may be documented.

---

6. Diagram Standards

When systems interact, diagrams are mandatory.

Permitted diagram types:

• Architecture diagrams
• Sequence diagrams
• State machines
• Economic flow diagrams

All diagrams must:

• Use valid Mermaid syntax
• Render without errors
• Reflect current architecture

---

7. External Reference Standards

External content must:

• Be directly relevant
• Reinforce technical explanation
• Include contextual framing

Superficial embedding is prohibited.

---

8. Product-Forward Requirements

Where applicable, documentation must explain:

• Why this design exists
• Trade-offs vs alternatives
• Upgrade paths
• Modularity
• Real-world deployment implications

Marketing tone is prohibited unless explicitly scoped.

---

9. Prohibited Practices

The following are not permitted:

• Bullet-only explanation of complex systems
• Unverified claims
• Outdated architecture
• Cross-layer ambiguity
• TODO placeholders in published docs
• Speculative roadmap claims presented as fact

---

10. Social Preview Metadata (Mandatory)

All authored MDX pages must follow the Open Graph metadata policy.

For docs.json-routable pages and their localized equivalents:

• og:image is required
• og:image:alt is required
• og:image must point to a real local raster asset
• SVG and GitHub blob URLs are prohibited
• og:image:type, og:image:width, and og:image:height must be present

Canonical asset rules:

• Routable pages use the top-level tab image for their locale
• Non-routable authored pages use the site fallback image
• Shared OG assets live under snippets/assets/media/og-images/

Accessibility rule:

• og:image:alt must describe the social preview image content, not just repeat a filename or path

Automation rule:

• Use operations/scripts/snippets/generate-og-images.js to generate the canonical PNG assets and manifest
• Use operations/scripts/snippets/generate-seo.js to normalise frontmatter to the canonical asset set

---

11. Publication Readiness Checklist

Before publication confirm:

• Technical accuracy
• Contract verifiability
• Mathematical correctness
• Diagram validity
• Reference validity
• Layer clarity
• No speculative language

---

12. Source of Truth Requirement

All documentation should:

• Align with canonical terminology
• Avoid regression
• Explicitly justify structural changes