> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 localised 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