RFP — Documentation Restructure

Date Issued: 2025-09-17
Issued By: Livepeer Foundation
Contact: Rich O’Grady


1. Objective

Restructure, refresh, and modernize Livepeer’s documentation so that it is stakeholder-focused, AI-first, and future-proofed. It should cater to the core personas of the Livepeer project: developers, delegators, gateway operators and orchestrators.


2. Problem Statement

Current Livepeer docs suffer from:

  • Complicated onboarding: User journeys (node operators, app builders, delegators, gateway providers) are hidden behind toggles instead of clear entry points.
  • Outdated or inconsistent content: Deprecated APIs, stale references, incomplete AI coverage, and fragmented changelogs.
  • Brand & duplication: Studio-specific guidance is mixed into core docs; AI SDKs and APIs are duplicated across gateways.
  • Weak site integration: Poor linkage between website, explorer, governance portal, and docs. Too many Studio dashboard references.


3. Desired Outcome

Success is a single-source-of-truth documentation system that:

  • Leads with clear stakeholder-focused onboarding and goal-oriented entry points.
  • Cleanly separates AI Jobs vs Transcoding Jobs while still surfacing cross-cutting resources (SDKs, APIs, CLI, on-chain/network).
  • Fully deprecates Studio content with redirects and zero broken links.
  • Provides AI-first documentation: semantically structured, LLM-readable, with embedded natural language search/assistant.
  • Consolidates changelogs and introduces versioning / deprecation tracking.
  • Establishes a style guide, contribution model, and ownership playbook for consistency.
  • Integrates seamlessly with the broader Livepeer ecosystem (website, explorer, governance, dashboards).


4. Deliverables

(i) Present New Documentation Strategy

Goal: Create a new outline for Livepeer documentation, including full map of current documentation, a clear information architecture and timeline for writing new documents.

Requirements:

  • Identify core stakeholder groups (Livepeer Foundation, Livepeer Inc, AI SPE, Cloud SPE, Streamplace, Frameworks and more)
  • Conduct of all docs pages with status recommendations across the 4 categories (Developers, Delegators, Orchestrators, Gateway Operators)
    • Developers: clean up deprecated sections and plan integrations with new gateway products (Streamplace, Frameworks, Daydream and more)
    • Orchestrators: simplify documentation to easy onboarding with plan for support in Discord.
    • Delegators: integrate new video content to make it easy to delegate.
    • Gateways: streamline documentation and workflows with support from the Foundation.
  • Create plan for an updated sidebar, taxonomy, and breadcrumb structure.
  • Consolidation of multiple changelogs into a single canonical feed.
  • Onboard stakeholders to project management process

Outcome: A forum post detailing the new documentation to the community with a 1-week window RFC.

Demo Due Date: Friday 17th October

(ii) Re-Write Documentation

Goal: Systematically edit and rewrite new content to meet stakeholder needs with consistent accuracy and depth.

Requirements:

  • Work with core stakeholders to rewrite documentation
  • Make the documentation easily consumable by AI systems and empower users with an embedded assistant ( semantic headings, structured metadata, and machine-readable references (OpenAPI specs, JSON examples).
  • Integrate embedded natural-language search or AI assistant (leveraging Mintlify features) and ensure clear explanations and concise summaries for LLM parsing.
  • Rewrite quickstarts for both AI Jobs and Transcoding Jobs.
  • Migration guides for Studio users.
  • Integrate goal-based tutorials for each stakeholder type where possible.
  • Work with existing groups to incorporate starter repos, examples, and copy-paste snippets and full API/SDK/CLI references with updated coverage (including realtime + BYOC APIs).
  • Conduct review with core stakeholders with a clear RFC.

Outcome: First written draft of clear, accurate, and goal-oriented documentation that accelerates adoption and reduces support overhead.

Demo Due Date: Friday 7th November

(iii) V1 Documentation Live

Goal: Deliver a technically sound and reliable documentation site.

Requirements:

  • Implement redesigned IA and content in the current docs stack (Mintlify/Docusaurus).
  • Set up redirects, SEO and AEO optimization, and accessibility compliance (WCAG).
  • Integrate multilingual readiness and analytics tracking.
  • Integrate the documentation into the website.

Outcome: A responsive and performant documentation site with zero broken links, measurable engagement, and improved accessibility.

Demo Due Date: Friday 14th November

(iv) Public Workflow For Maintenance & Community Contributions

Goal: Create a consistent tone and a scalable contribution process.

Requirements:

  • Work with the Livepeer Foundation’s Technical Director to establish a unified voice and style guide (tone, terminology, formatting, accessibility).
  • Create contribution guidelines and PR workflow for community involvement.
  • Define and handover ownership and review process for maintaining quality.
  • Integrate multilingual readiness and analytics tracking.
  • Provide a clear ticketing system for reporting problems and patching fixes.

Outcome: A sustainable documentation process with consistent voice, tone, and governance.

Demo Due Date: Friday 5th December


5. Capabilities Required

Skills

  • Developer documentation strategy, IA design, technical writing.
  • Static site tooling, redirect management, docs CI pipelines.
  • SEO, accessibility, multilingual documentation workflows.

Knowledge

  • 1+ years experience with Livepeer ecosystem
  • Streaming/transcoding basics (FFmpeg, GPU workloads).
  • AI inference workflows basics, particularly working with APIs.
  • Open-source contribution models and GitHub-based workflows.
  • Comparative familiarity with best-in-class docs (e.g., Chainlink, Base, Solana).

Attitude

  • Community-first, collaborative, pragmatic.
  • Strong eye for clarity, consistency, and long-term maintainability.
  • Willingness to challenge outdated patterns and propose future-proof solutions.
  • Enjoyment in distilling complex technical concepts into minimal, user-focused documentation.

6. Proposal Requirements

Please include in your proposal:

  • Executive Summary - give an overview of the proposal and why you are suited.
  • Company / Contributor Overview & Capabilities - breakdown of each contributor with bio and relevant case studies.
  • Past Work & Experience - examples of docs restructures, especially for developer platforms.
  • Milestone Breakdown - giving a week-by-week breakdown of the project in line with the due dates and requirements above.
  • Pricing Breakdown - breakdown of payment by milestone with an optional ongoing support.

Though we recommend you use your own creativity in the proposal, an example template is here: Livepeer RFP — Proposal Template


7. RFP Timeline

  • Proposal Deadline: Wednesday 24th September 2025
  • Decision Announced: Friday 26th September 2025
  • Project Start: Monday 29th September 2025
  • Project Completion: Friday 5th December 2025


8. Proposal Submission Instructions

  • Format: PDF or Notion page (share with view access).
  • Proposal Deadline: 11:59pm GMT-7, Wednesday 24th September 2025.
  • Questions: reach out to Rich | Livepeer Foundation on the Livepeer Discord.
  • Proposal Updates: if you submit an early draft of the proposal, you are welcome to update your original proposal until the final deadline.
  • Payments: when thinking through your total budget, be mindful that payments will be paid out on milestone completion.
6 Likes

Hello all - submitting my RFP to help make Livepeer’s docs world-class! :fire: Look forward to working with the community here! :fire:

Team/Individual Name: Sidney Lane

Contact Information: sidney.lane.contact@gmail.com

Arbitrum Payment Address: 0x3ef3f79C03A27299636A8d16693e6d54f68264De [USDC on Arbitrum]

Total Funding Amount Requested: $25,000


Executive Summary

This proposal outlines a comprehensive plan to restructure and modernise Livepeer’s documentation in line with the Livepeer Foundation’s RFP, making it “stakeholder-focused, AI-first, and future-proofed”

My approach emphasises clear, concise, and well-structured content (following industry best practices) and directly targets Livepeer’s core personas – developers, delegators, gateway operators, and orchestrators – by providing goal-oriented & relatable tutorials, migration guides, and reference materials for each. I achieve this by using the product myself as well as through community engagement & mitigating against pain points.

Over a 10-week engagement (Sept 29–Dec 5, 2025), I will conduct a full content audit and IA redesign, rewrite key guides (quickstarts, API/SDK references, tutorials), implement the new site with embedded AI-friendly features, and deliver style/contribution guidelines.


My Experience & Background

With a background as a leader in a decentralised Compute & AI startup, 8 years of DevRel experience, and over 4 years in crypto & blockchain, I bring the combined perspective of a technical leader and strategist. I’ve also worked as a developer, a researcher, a project manager and a consultant across IBM, the University of Sydney, and Accenture, and I hold degrees in Mechatronics Engineering & Computer Science.

As former deAI startup leadership, developer and prior DevRel, I bring the combined experience of my developer skills, business understanding and communication expertise to this role. I also bring a clear understanding of the level of technical difficulty & product pain points that can be faced by new product users in decentralised technologies and the ability to ELI5 and provide content that targets new users’ interests and targets business goals.


Contributor Overview & Capabilities

I am applying as an individual contributor. My profile and skills include:

  • Technical leadership: Former leadership at a decentralised AI (deAI) startup, where I led product strategy and technical development while building and supporting a community with multiple actors (compute providers, users, partners & AI developers).

  • Blockchain and decentralised systems: 5 years of experience in crypto, including as a devRel & devX lead with a distributed storage company. I understand the Livepeer ecosystem and related concepts like transcoding, decentralised nodes, and staking/delegation. This directly aligns with the RFP’s requirement for “1+ years experience with [the] Livepeer ecosystem” and “streaming/transcoding basics (FFmpeg, GPU workloads)”

  • Technical expertise: I hold degrees in Mechatronics and Computer Science, giving me solid foundations in hardware (e.g. GPUs, video encoding) and software. This technical literacy enables me to accurately document low-level processes (like Livepeer Broadcaster setup or GPU transcoding) and high-level architecture (orchestrators, gateways, on-chain components).

  • Documentation & IA skills: I have led multiple documentation projects using static-site tooling (Docusaurus/Mintlify, GitHub Pages) and established clear information architectures. My skills align with the RFP’s “developer documentation strategy, Information Architecture design, [and] technical writing” requirements. I also understand SEO, accessibility (WCAG), and multilingual workflows, ensuring the final site is discoverable and inclusive.

  • Open-source and community focus: I am experienced with GitHub-based contribution models and community collaboration. As the RFP seeks a “community-first, collaborative, pragmatic” attitude, I will engage core stakeholders (Livepeer Foundation, Livepeer Inc., Streamplace, SPEs) throughout the process and will distil technical complexity into user-focused documentation. I’ll also provide progressive community workflows for a builder’s funnel journey, and can integrate automated escalations, aggregation of questions & AI features & capabilities.


Proposed Approach & Philosophy

To improve Livepeer’s documentation, I will follow a user-centric, AI-enabled, and systematic approach:

  • Stakeholder-focused content audit: First, I will identify the core personas (developers, delegators, orchestrators, gateway operators) and map their journeys. I will also define business & product targets in order to capture multiple KPIs within the docs (eg, Join the community, contact, encouragement to contribute). I will also aggregate common questions from the forum, GitHub and Discord for inclusion gaps. This will also help me to define a tone and culture for the docs (should there be gifs & fun names, etc., for example). I will inventory all existing docs (Livepeer docs, Studio guides, etc.) and assess each page for relevance, accuracy, and stakeholder fit. This audit will reveal outdated or redundant content and highlight gaps.

  • New Information Architecture (IA): Following the audit & information gathering process, I can then propose a new format for documentation that will target user journeys more effectively and promote community engagement while minimising pain points. Using insights from the audit, I will design a clear, hierarchical IA. This may involve restructuring the sidebar, taxonomy, and breadcrumbs to create distinct sections for each user type. Each major section (e.g. Developers, Delegators, Orchestrators, Gateways) will present goal-oriented entry points (“how to start as a delegator”, “setting up an orchestrator node”, etc.). I will apply the Diátaxis framework, providing tutorials (step-by-step guides), how-to and task-based guides (for common operations), conceptual explanations (network architecture, key concepts), and reference (detailed SDK/API docs) with help from the current team and engineers to fill gaps where needed. This ensures the content is easy to scan and lets readers find what they need quickly. Clear headings, bullet lists, and indexed tables of contents will make each page accessible and AI-readable, and SEO considerations can also be optimised.

  • Writing for clarity and AI: I will rewrite all content in plain, concise language to improve clarity, as well as target an uplifting and fun vibe for users (without compromising integrity or burdening the journey). Each document will start with the most important information, and any jargon will be defined or simplified, as recommended by best practices. Importantly, I will embed metadata and semantic structure to be “AI-first, with an embedded natural language search/assistant”. This means using descriptive headings and machine-readable examples (OpenAPI specs, JSON snippets) so that Livepeer’s Mintlify/Docusaurus site can support vector search or chatbot integration. In practice, the documentation will include explicit summaries and keywords for each section, enabling LLMs to retrieve and explain content to users easily.

  • Targeted Guides and Tutorials: I will produce tailored content for each persona. For developers, this includes quickstarts for both AI Jobs and Transcoding Jobs (e.g. “Build your first AI-powered Livepeer app”), full SDK/API references (including new gateway products like Streamplace and Daydream), and code examples. For orchestrators, I will create a streamlined node setup guide with links to Discord support. Delegator docs will feature simple delegation walkthroughs, perhaps incorporating short video demos or diagrams if time permits. Gateway operators (Streamplace, etc.) will have their own section with step-by-step integration guides. Migration guides will help Studio users transition to the new system. In all cases, I will organise content by use case (goal-based tutorials) as the RFP specifies. We will target more than new developers by providing level-up guides where possible and giving ideas on usage - not just technical descriptions - perhaps highlighting community & partner projects.

  • Implementation and SEO: After drafting content, I will implement the revised IA and pages in the chosen docs stack (Mintlify/Docusaurus). I will set up 301 redirects from old URLs to new ones to ensure a single source of truth and avoid broken links. Deprecated pages can be versioned in case of need. AI-first SEO best practices (meta tags, descriptive URLs, sitemap) and accessibility considerations (WCAG) can be applied throughout. Multilingual readiness can also be configured, and basic analytics (to track engagement) will be integrated. AI features and flows can also be added where time permits.

  • Governance and Style: To ensure long-term maintainability, I will develop a documentation style guide (tone, terminology, formatting) and a contribution model. This will align with the RFP’s vision of a unified voice and clear PR workflow. I can also integrate automated triggering processes for approvals into this flow ie github → discord messages. I will hand over a clear process for reporting issues and updating content (e.g. a GitHub issue template or Discord channel for docs feedback).

Throughout, I will work closely with Livepeer’s teams, conducting reviews and RFCs (as per milestones) to gather feedback. This collaborative, iterative method matches the “community-first, collaborative” attitude highlighted by the Foundation and will lead to a user-focused outcome.


Milestones & Timeline

I’ve separated the milestones into essentials, desired and stretch goals to accommodate any flexibility needed with timing, given a tight timeframe for delivery. KPIs can be set accordingly.

Phase 1 – Foundation (Weeks 1–3)

Lay the groundwork: audit, tone, and architecture.

Essential:

  • Full content audit (Livepeer docs, Studio guides, forum, GitHub, Discord).

  • Persona & journey mapping (developers, delegators, orchestrators, gateway operators).
    Draft tone & culture guidelines (voice, fun vs formal balance, engagement hooks).

  • Initial Information Architecture (IA) proposal.

Desired:

  • Early KPI mapping (community join, contribution prompts, contact flows).
    Aggregation of common Q&A from community sources for gap-filling.

Stretch:

  • Draft initial “content matrix” mapping every doc to persona, goal, and KPI.

  • Mockups of possible UI/UX (sidebar/navigation layouts).

Phase 2 – Alignment & Review (Weeks 4–5)

Validate structure, test tone, and begin high-priority rewrites.

Essential:

  • Refine IA after Livepeer team + community feedback.

  • Rewrites for top-priority docs:

    • Developer quickstarts (AI Jobs, Transcoding Jobs).

    • Orchestrator setup.

    • Delegator staking walkthrough.

Desired:

  • Draft migration guide (Studio → new APIs).

  • Tone experiments (gifs, diagrams, fun naming) applied to early docs.

Stretch:

  • Run community RFC on tone & layout prototypes.

  • Create first visuals (flowcharts, system overview diagrams).

Phase 3 – Build & Expand (Weeks 6–8)

Deliver breadth: cover all personas, implement IA live, and expand tutorials.

Essential:

  • Implement new IA in Mintlify/Docusaurus.

  • Expand rewrites: Gateway operators, SDK/API/CLI references.
    Ensure metadata/semantic structure for AI-first search.

Desired:

  • Add level-up tutorials (beyond basics).

  • Highlight community/partner projects as inspiration.

  • Initial SEO & accessibility pass.

Stretch:

  • Add embedded video snippets or interactive demos.

  • Prepare multilingual scaffolding (no translations yet).

Phase 4 – Finalise & Future-Proof (Weeks 9–10)

Polish, hand over, and ensure sustainability.

Essential:

  • Final docs package live with redirects, SEO, and accessibility fixes.

  • Documentation style guide (voice, terminology, formatting).

  • Contribution workflow (GitHub → Discord triggers, PR templates).

Desired:

  • Analytics setup to monitor usage (page views, search queries, drop-offs).

  • Maintenance playbook for ongoing updates.

Stretch:

  • Advanced tutorials (use-case guides, “Build your first app in 10 minutes”).

  • Glossary of key terms for new community members.


Deliverables

By project completion, I will deliver:

  • Content Audit Report: A spreadsheet or visual map of existing documentation, showing status (keep, rewrite, archive) for every topic, organised by persona.

  • Information Architecture Outline: A new site map and sidebar structure, with taxonomic categorisation of content (by stakeholder type and task).

  • Rewritten Documentation: High-quality pages covering:

    • Tutorials and quickstarts for AI and transcoding jobs (for developers).

    • Delegator guides (including new video tutorials or diagrams) to simplify staking.

    • Orchestrator onboarding (node setup, funding, monitoring).

    • Gateway operator guides for integration with Livepeer Cloud SPEs.

    • Migration instructions for migrating from Studio to the core Livepeer APIs.

    • Complete API/SDK/CLI reference material (including real-time and BYOC APIs).
      Any necessary diagrams or visual assets (network architecture, workflow charts) to aid understanding.

  • Fully Deployed Docs Site: A Mintlify/Docusaurus-based documentation portal with all new content, integrated into the Livepeer website. This site will have semantic markup, an embedded natural-language search/assistant feature, and a consolidated changelog/version history.

  • Redirects & SEO/Analytics Setup: Configured 301 redirects for legacy URLs, optimised metadata for search, and basic analytics reporting on documentation usage.

  • Style Guide & Contribution Process: A documented voice and style guide (terminology, formatting, accessibility guidelines) and a clear contribution/PR workflow (templates and processes) for future updates, fulfilling the “Public Workflow” milestone

  • Recommendations for future work: I’ll detail any recommendations or thoughts for future work that could deliver even more value to Livepeer & its ecosystem.


Budget & Pricing

My budget is based on 25 hours of work per week over a 10-week period. All essential needs will be delivered within this timeframe, and desired outcomes should also be possible. Stretch goals can be attempted where time permits.


Conclusion

With a strategic, user-focused approach and the technical background to understand Livepeer’s ecosystem, I am confident in delivering documentation that meets and exceeds the RFP’s goals. My plan follows best practices (clear writing, structured content) and aligns with Livepeer’s vision of future-proof, AI-ready docs. I look forward to collaborating with the Livepeer team & community to make this project a success.


Livepeer / Internal References

  1. Livepeer RFP — Documentation Restructure
    The main RFP document you’re responding to. It defines the objectives (“stakeholder-focused, AI-first, future-proofed”), personas (developers, delegators, gateway operators, orchestrators), and the problem areas.

  2. Livepeer Cloud SPE Proposal
    A proposal that includes documentation goals: “Clear and easy documentation for a go-Livepeer Broadcaster”, etc. Useful as an example of scope and deliverables in Livepeer ecosystem.

  3. “How to propose changes to Livepeer’s Documentation”
    Shows the existing contribution model and process around documentation changes. It can help show you understand the workflows in place.

  4. Open Source Funding SPE
    A proposal focused on supporting open-source projects. Can illustrate how Livepeer values documentation and infrastructure work in the broader context of ecosystem support.


External / Best Practices References

  1. Diátaxis Framework
    (Mentioned in your draft approach) — an established method for structuring technical documentation into tutorials, how-tos, conceptual docs, and references. While not a Livepeer document, this is a recognised best practice in developer docs design.

  2. WCAG Accessibility Guidelines
    Ensures your documentation is usable for people with disabilities. Many organisations treat WCAG (Web Content Accessibility Guidelines) as standard. Including this shows attention to usability.

  3. SEO Best Practices / Metadata / Semantic Markup
    Applying semantic headings, URL structures, meta tags, sitemaps, etc. are general best practice for documentation and websites. You can mention references from Docusaurus or Mintlify docs about how metadata helps with search/discoverability.

  4. Community Feedback / Forum / GitHub Issues
    The plan to aggregate questions from Livepeer’s forum, Discord, GitHub (to capture content gaps) is aligned with community-driven documentation improvement practices used in many open source ecosystems.

Hello all,
I’m coming over from RaidGuild to deliver our proposal for Livepeer’s Documentation Restructure. We’ve admired Livepeer for years and excited to submit our approach for consideration.

We’d love to hear your thoughts and answer any questions about our strategy for modernizing Livepeer’s documentation ecosystem.

Cheers,
Ian

Livepeer Documentation Restructure Proposal

Transform Livepeer’s documentation into a stakeholder-focused, AI-first, future-proof knowledge system

Executive Summary

RaidGuild proposes to transform Livepeer’s documentation from a fragmented, toggle-heavy system into a streamlined, AI-optimized, stakeholder-focused knowledge platform. Our approach prioritizes clear user journeys, eliminates content duplication, and establishes sustainable maintenance workflows that will scale with Livepeer’s growth.

As Web3’s premier decentralized development collective with 154 DAO members and 200+ successful raids since 2019, we bring unparalleled experience in complex protocol documentation restructures. We are currently deep into restructuring the Pocket Network Documentation, demonstrating our ability to handle sophisticated documentation upgrades for established Web3 protocols with multiple stakeholder groups and complex technical architectures.

Company Overview & Capabilities

RaidGuild is Web3’s premier decentralized development collective, trusted by leading protocols since 2019. With 154 DAO members and 200+ successful raids, we specialize in mission-critical Web3 solutions that drive real business impact across infrastructure, DeFi, gaming, and developer tooling.

Core Capabilities

  • Protocol Documentation Strategy - Multi-stakeholder content architecture for complex Web3 infrastructure
  • Cross-Chain Infrastructure Expertise - Deep experience with bridges, RPC gateways, and multi-network protocols
  • Community-Driven Development - Scalable contribution workflows and decentralized governance integration
  • AI-Optimized Content Creation - LLM-readable documentation with semantic structure and embedded search
  • Developer Experience Design - User journey optimization for technical stakeholders and node operators

Proven Documentation & Infrastructure Track Record

Our experience spans the full spectrum of Web3 protocol documentation and infrastructure development:

  • Pocket Network - Currently restructuring comprehensive documentation for the original DePIN project.
  • PORTERS RPC Gateway - Built scalable documentation for decentralized RPC infrastructure handling multi-chain complexity
  • Hypercerts Protocol - Created technical documentation for transparent grant accountability systems
  • Gnosis Bridge - Documented cross-chain infrastructure that facilitated $367M in bridged assets for 33k+ users
  • Aura BrightID - Structured complex identity verification documentation with gamification mechanics

Experience & Why We’re the Right Fit

1. Complex Web3 Protocol Documentation Expertise

Our ongoing Pocket Network documentation restructure directly parallels Livepeer’s challenges:

  • Consolidating fragmented documentation across RPC infrastructure, node operations, and developer APIs
  • Managing multiple stakeholder groups (node runners, developers, delegators, gateway operators)
  • Implementing AI-first content structure for complex technical workflows

Additional relevant experience:

  • PORTERS RPC Gateway: Documented infrastructure serving 1B+ requests across 40+ networks
  • Gnosis Bridge: Created user-friendly documentation for $367M in cross-chain asset transfers

2. AI-First Documentation Specialization

  • Deep experience with AI inference platform documentation (GPT, Stable Diffusion APIs)
  • Proven track record creating LLM-optimized content structures
  • Expertise in semantic heading hierarchy and machine-readable documentation
  • Portfolio Examples:
    • AI Protocol Documentation - Semantic structure with embedded assistant
    • Inference Network Docs - Multi-stakeholder AI platform documentation
    • ML Pipeline Docs - Complex technical workflows simplified for developers

3. Infrastructure & Multi-Stakeholder Platform Knowledge

  • Deep experience with decentralized infrastructure protocols (RPC networks, bridges, node operations)
  • Proven track record managing complex stakeholder ecosystems (developers, operators, delegators)
  • Understanding of streaming/transcoding workflows through infrastructure development experience
  • Active Web3 community engagement with contributions to major protocol documentation

Project Leadership

bendictvs — Lead Information Architect + Technical Writer

As the proposed Lead Information Architect, benedictvs brings expertise in Web3 documentation overhauls, DAO governance, and AI-optimized content. He was elected into the role as Product Tech Resident at Nouns Builder (nouns.build) to restructure the platforms offering through a revenue generation strategy and leading the product build out.

This role includes maintaining protocol docs and leading a major update that consolidated guides, enhanced user journeys for DAO operators and developers, and included guides for every day users. The below snapshot from one of our documentation product sessions showcases at Nouns Builder what working with benedictvs and RaidGuild could look like for Livepeer.

Key Skills & Qualifications

  • Web3 Documentation Restructuring: Led revamps for Nouns Builder and similar protocols, creating stakeholder-focused architectures that parallel Livepeer’s needs
  • AI-First Content Design: Builds machine-readable structures with semantic embedding, drawn from over 5 years in nationally and EU-funded digital identity and verifiable data projects
  • Project Management & Grants: Secured over 500,000 in grant funding, including the European Commission over the past 2 years and held budget responsibility for mid 6 figure government funded projects that required extensive documentation and compliance.
  • DAO & Governance Expertise: Raid Guild DAO member since 2022, and part of the set up of Scroll L2 DAO; Member of the Metagov Grant Innovation Lab, PhD candidate in digital infrastructure, specializing in digital infrastructure governance and compliance (MiCA, EUDIF), and multi-stakeholder content writing.
  • Developer Experience Optimization: Designs user journeys for technical stakeholders in projects like Smart Invoice and Nouns Builder Protocol, improving onboarding and workflow clarity.

Ben’s academic, product, and Web3 background ensures an AI-optimized, scalable system for Livepeer as substantiated by the experience and expertise showcased in his CV and verifiable references of work upon request.

PROJECT BREAKDOWN - $24,000

Timeline: 10 weeks (September 29 - December 5, 2025)

Deliverable 1: Documentation Strategy & Information Architecture

Timeline: 3 weeks (September 29 - October 17, 2025) Demo Due: Friday, October 17, 2025

Total Effort: 60 hours - $6,000

Task Description Hours Owner
Stakeholder Research & Mapping Interview core stakeholder groups, map current user journeys, identify pain points 10 hours Lead Information Architect
Content Audit & Classification Complete inventory of existing docs with status recommendations across 4 personas 12 hours Technical Writer + IA Lead
Information Architecture Design New sidebar structure, taxonomy, breadcrumb hierarchy for stakeholder-focused navigation 9 hours Lead Information Architect
User Journey Mapping Clear entry points and goal-oriented paths for each stakeholder type 6 hours UX Researcher + IA Lead
Changelog Consolidation Plan Strategy for unified changelog with versioning and deprecation tracking 8 hours Technical Writer
AI-First Content Strategy Semantic structure plan, metadata schema, LLM optimization guidelines 8 hours AI Documentation Specialist
Community RFC Preparation Forum post creation, stakeholder onboarding, project management setup 2 hours Project Manager
Stakeholder Review & Iteration Feedback integration, plan refinement, approval process 5 hours Project Manager + IA Lead

Key Deliverables:

  • Comprehensive current state audit with specific recommendations
  • New information architecture with visual site maps
  • Stakeholder-specific user journey documentation
  • Community RFC post for 1-week feedback period
  • Project management dashboard with stakeholder access

Deliverable 2: Content Rewrite & AI Optimization

Timeline: 3 weeks (October 20 - November 7, 2025) Demo Due: Friday, November 7, 2025

Total Effort: 70 hours - $7,000

Task Description Hours Owner
Stakeholder Collaboration Setup Working sessions with Foundation, Inc, AI SPE, Cloud SPE teams 5 hours Project Manager
AI Jobs Documentation Rewrite Complete rewrite of AI inference workflows, quickstarts, and API references 16 hours AI Documentation Specialist
Transcoding Jobs Documentation Modernized transcoding documentation with clear separation from AI jobs 14 hours Technical Writer
Cross-Cutting Resources Integration Unified SDKs, APIs, CLI documentation accessible across both job types 12 hours Technical Writer + Developer
Migration Guides Creation Studio deprecation guides with clear migration paths and redirects 8 hours Technical Writer
Goal-Based Tutorials Stakeholder-specific tutorials with copy-paste examples and starter repos 10 hours Developer + Technical Writer
Stakeholder Review Process Content review cycles with core stakeholders and RFC preparation 5 hours Project Manager

Key Deliverables:

  • Complete rewritten documentation for AI and Transcoding workflows
  • Migration guides for Studio users with zero broken links
  • Stakeholder-specific quickstart guides and tutorials
  • Machine-readable API documentation with updated coverage
  • First draft ready for community RFC

Deliverable 3: Technical Implementation & Launch

Timeline: 2 weeks (November 10 - November 14, 2025)

Demo Due: Friday, November 14, 2025

Total Effort: 40 hours - $4,000

Task Description Hours Owner
Mintlify Implementation New IA implementation in existing docs stack with responsive design 12 hours Frontend Developer
AI Assistant Integration Embedded natural language search and AI assistant setup 8 hours AI Documentation Specialist
Redirect Management Complete redirect mapping, SEO optimization, broken link elimination 6 hours Frontend Developer
Analytics & Performance Analytics tracking, performance optimization, accessibility compliance (WCAG) 4 hours Frontend Developer
Multilingual Readiness Infrastructure setup for future multilingual support 3 hours Frontend Developer
Website Integration Seamless integration with broader Livepeer ecosystem (explorer, governance) 4 hours Frontend Developer
Quality Assurance Testing Comprehensive testing across devices, browsers, and user flows 2 hours QA Specialist
Launch Coordination Go-live preparation, stakeholder communication, launch support 1 hour Project Manager

Key Deliverables:

  • Fully implemented documentation site with new IA
  • Functional AI assistant and semantic search
  • Zero broken links with comprehensive redirect mapping
  • Analytics dashboard and performance monitoring
  • WCAG-compliant accessible documentation

Deliverable 4: Maintenance Workflow & Community Integration

Timeline: 2 weeks (November 17 - December 5, 2025) Demo Due: Friday, December 5, 2025

Total Effort: 50 hours - $5,000

Task Description Hours Owner
Style Guide Creation Comprehensive voice, tone, terminology, and formatting guidelines 10 hours Technical Writer + IA Lead
Contribution Workflow Setup GitHub-based PR workflow, review processes, community onboarding docs 9 hours Developer + Technical Writer
Establishing Documentation Governance & Improvement Protocols Establish a governance structure for future reviews, community pull requests, and ongoing revisions to documentation on a high level of quality 6 hours Project Manager + Technical Director
Community Training Materials Written guides for community contributors 8 hours Technical Writer
Ticketing System Integration Issue reporting system, fix prioritization, patch deployment workflow 5 hours Developer
Documentation Analytics Success metrics, engagement tracking, community contribution monitoring 4 hours Developer
Handover Process Knowledge transfer to Foundation team, ongoing support documentation 4 hours Project Manager
30-Day Post-Launch Support Bug fixes, community questions, workflow refinements 4 hours Full Team

Key Deliverables:

  • Complete style guide and contribution guidelines
  • Functional community contribution workflow
  • Integrated ticketing and issue resolution system
  • Handover documentation and team training
  • 30-day post-launch support and refinement

Team Structure

Our specialized documentation team is assembled for this project:

Team Member Role Responsibilities
Ben Biedermann Lead Information Architect + Technical Writer IA design, stakeholder research, user journey mapping, content rewriting, transcoding docs
Ziavash Frontend Developer + AI Documentation Specialist Mintlify implementation, redirects, performance optimization, AI-first optimization, semantic structure
Ian Boucher Project Manager Stakeholder coordination, timeline management, community RFC

Pricing Breakdown

Deliverable Timeline Total Hours Investment
Documentation Strategy & IA 3 weeks 60 hours $6,000
Content Rewrite & AI Optimization 3 weeks 70 hours $7,000
Technical Implementation & Launch 2 weeks 40 hours $4,000
Maintenance Workflow & Community 2 weeks 50 hours $5,000
Contingency Reserve* ** 20 hours $2,000
TOTAL 10 Weeks 220 hours $24,000

*The contingency reserve ensures project resilience against unforeseen technical complexities and stakeholder requirements that commonly emerge in large-scale documentation restructures. This reserve will only be utilized with explicit client approval for validated scope additions, or released as part of final milestone completion.

Ongoing Support Options

Documentation Maintenance: $75/hour (10-30 hours/month available)

  • Content updates and additions
  • Community contribution review
  • Performance monitoring and optimization
  • Quarterly documentation audits

First 30 days post-launch support: Included in project cost

1 Like

Hi Livepeer team,

We’re excited to further our contribution to the Foundation through this RFP proposal and would be delighted to help you and the builders out there looking to take advantage of your technology. Please see the proposal from Myosin below:


:telescope: Background

Livepeer Foundation stewards the long-term vision, ecosystem growth, and core development of the Livepeer network. Following the creation of the core network architecture by Livepeer Inc and the community-governed treasury, the launch of the LF marks a new chapter in the progressive decentralization of the Livepeer project.

The Foundation’s role is to ensure that the Livepeer project builds a thriving ecosystem of founders, applications, and gateways alongside a highly-performant, capable, and secure network that is truly accountable and governed by token holders. In order to do that, LF needs excellent relations with developers and that can often start with well laid out and organized technical documentation.


:luggage: The Brief

Livepeer Foundation has tasked Myosin with completely overhauling their documentation system, through a publicly available RFP. The goal is to create a stakeholder-focused, AI-first documentation structure, modernize content for all user personas, and establish sustainable maintenance processes to drive growth for the ecosystem.


:brain: The Strategy

Myosin has been refining a marketing playbook that improves brand awareness, drives community engagement and accelerates user adoption.

Documentation Architecture Redesign

We’ll conduct a comprehensive audit of existing documentation, identifying gaps, redundancies, and outdated content (we often receive praise for how thorough our work is on auditing, which isn’t the exciting work but it’s so important).

Where appropriate, we’ll verify key gateway references by running them against staging to validate core flows.

Develop a new Information Architecture

Working closely with key stakeholders, we’ll develop a new information architecture that prioritizes user journeys for developers, delegators, orchestrators, and gateway operators.

This restructuring will create clear entry points for each persona while maintaining cross-cutting resources that benefit all users.

Gateway Documentation Audits & Standards (link-out model)

In line with the RFP’s single-source-of-truth and no-duplication goals, we will not host partner API docs on the Foundation site. Instead, we will:

  • Audit 3–4 gateway/provider documentation sets and produce summaries.

  • Define “Docs Standards for Gateway Partners” (IA, naming, versioning, searchability, error patterns).

  • Implement a clean link-out model from Foundation docs to Gateway Partner docs once standards are met, with clear attribution.

Technical Writing

We will prioritize the top 1–2 personas and deliver a great Transcoding Quickstart experience. The audit and IA will cover all personas (Developers, Delegators, Orchestrators, Gateway Operators); non‑priority personas receive structural updates, and deprecations/redirects. Within the core timeline, we’ll deliberately balance effort across three tracks rather than trying to do everything at once:

(1) Studio → Gateway migration: an agnostic guide mapping Studio concepts/flows to current stakeholder gateways, with standards‑based link‑outs (no duplicate hosting)

(2) Targeted API/SDK references added where needed

(3) Light‑touch updates (where needed) to core pages (e.g., Getting Started, Core Concepts): accuracy fixes, deprecations/redirects, IA alignment.

The audit will determine exact priorities. If time allows within the core timeline (after other core deliverables), we can expand to additional tasks.

We will build a foundation of well structured, human-readable documentation and future-proof this by using clean semantics and logical headings. This foundation will be possible to deliver within your timeline and can then be layered with AI features built on top of a stable base.

Sustainable Documentation Governance

Beyond just creating content, we’ll establish the systems and processes needed for long-term documentation health. This includes developing style guides, contribution workflows, and ownership models that ensure consistency and quality over time.

We’ll work with the Livepeer Foundation to create clear maintenance protocols that enable both internal teams and community contributors to participate in documentation upkeep.


:bullseye: Objectives and Key Results (OKRs)

The key objectives of this project are to restructure the documentation architecture, modernize content for all user personas, and establish sustainable maintenance processes for Livepeer Foundation.

This project will be assessed by the following metrics:

  • Reduction in support tickets related to documentation confusion

  • Establishment of clear contribution workflows with measurable community participation

  • Zero broken links on all pages we create or edit; redirects added for any moved/renamed pages; out-of-scope issues documented with recommendations.

  • Decouple protocol docs from gateway-specific APIs; implement a standards-based link-out model to partner docs (no duplicate hosting)


:glowing_star: Our Proposal

We propose a project to completely transform Livepeer’s documentation system with a focus on stakeholder needs, AI-readiness, and sustainable governance.

Documentation Strategy & Architecture

  • Internal docs audit (Foundation) with stakeholder‑specific recommendations

  • Development of new information architecture with clear user journeys

  • Creation of a consolidated changelog and versioning system

  • Gateway/provider docs audits (3–4) with summaries and “Docs Standards for Gateway Partners”; implement link-out IA and attribution

  • Draft a forum post detailing the changes to get feedback and generate excitement from the community

Content Development & Modernization

  • Comprehensive rewrite of core documentation for the top 1-2 primary stakeholder groups

  • Creation of goal-oriented Quickstarts for Transcoding Jobs

  • Studio → Gateway migration (most common path): an agnostic guide that maps Studio concepts/flows to current gateways, with link‑outs to partner documentation that meets Foundation standards. No duplicate hosting of partner API docs.

  • Audit and scaffold API/SDK sections; integrate existing API references and SDK links via link-outs to gateway/provider docs.

  • Work with existing groups (Livepeer Inc, AI SPE, Cloud SPE, and gateway providers) to incorporate their starter repos, copy‑paste snippets, and full API/SDK/CLI references via a standards‑based link‑out model; we do not duplicate or host partner API docs.

Governance & Sustainability Framework

  • Creation of documentation style guide and voice/tone guidelines

  • Documentation of suggested workflows and PR templates

  • Establishment of ownership and review processes

  • Planning and recommendations around documentation analytics and feedback systems


:tear_off_calendar: Project Plan

PHASE ONE (Documentation Strategy & Planning)

We’ll conduct a thorough assessment of the current documentation landscape and develop a comprehensive strategy for restructuring.

Week 1: Stakeholder interviews and documentation audit

  • Conduct interviews with key stakeholders (Livepeer Foundation, Livepeer Inc, AI SPE, Cloud SPE, etc.)

  • Complete comprehensive audit of existing documentation

  • Identify gateway contacts; request access to their docs/specs.

  • Identify core user journeys and pain points

Week 2: Information architecture development

  • Create new documentation structure with clear stakeholder entry points

  • Begin gateway early evaluations (rapid triage for 3–4 gateways), start early “Docs Standards for Gateway Partners”

  • Develop sidebar, taxonomy, and breadcrumb structure

  • Plan for consolidation of changelogs and versioning system

Week 3: Strategy finalization and RFC

  • Finalize documentation strategy with stakeholder input

  • Prepare forum post for community RFC

  • Establish project management processes and tools

  • Present new documentation strategy (Due: October 17th)

PHASE TWO (Content Development)

We’ll systematically work with core stakeholders to rewrite and restructure content to align with the new architecture and meet stakeholder needs.

Week 4-5: Core content development

  • Begin rewriting/editing documentation for primary stakeholder groups

  • Develop/edit Quickstart for Transcoding Jobs

  • Gateway partner working sessions on must‑fix items

  • Deliver ongoing rolling gateway summaries

Week 6-7: Advanced content development

  • Implement link-out IA and attribution from Foundation docs

  • Integrate targeted references where needed

  • Complete first draft of documentation (Due: November 7th)

PHASE THREE (Implementation & Governance)
We’ll implement the new documentation system and establish processes for long-term maintenance.

Week 8: Technical implementation

  • Deploy redesigned IA and content in current docs stack

  • Set up redirects and ensure zero broken links

  • Launch V1 documentation (Due: November 14th)

Weeks 9-12: Governance and handover

  • Develop style guide and contribution guidelines

  • Create PR workflow for community involvement

  • Establish ownership and review processes

  • Complete governance framework and handover (Due: December 5th)

This timeline is approximate and subject to change based on stakeholder feedback and technical considerations. Some examples of delays could be client-side decision-making or coding bugs uncovered that require engineering fixes.

We will work closely with the Livepeer Foundation team throughout to align on priorities and optimize based on learnings.


:busts_in_silhouette: Your Myosin Team

Your Myosin team will be assembled from our global network of documentation specialists, technical writers, and DevRel experts. We’ll provide a dedicated team with experience in blockchain documentation, developer experience, and technical content creation.

Bettina Sosa - Technical Designer

Bettina Sosa is a software engineer, designer, and Web3 builder with deep expertise bridging development, technical advocacy, and product innovation, with award-winning design work. Her roots span full-stack engineering and design, and her passion is combining software, cryptography, and user experience to build next-gen systems. She was the founding full-stack engineer at Sojo, responsible for designing, developing, and deploying the company’s core platform for on-demand clothing repairs and customizations. She later joined Catapult Labs as a founding full-stack engineer, where she developed the company’s flagship Web3 profiles platform for decentralized networking and went on to design decentralized financial primitives (including OTC crypto markets, collateral management, and margin trading systems).

Bettina currently leads Developer Relations at Myosin as a Guild Lead. More recently, Bettina has focused on developer relations, cryptographic systems, and community growth. She served as Head of Engineering & AI at Partisia Blockchain, combining cryptography, MPC, and AI to expand its engineer ecosystem. Her fluency in Rust, Solidity, TypeScript, product design, and community engagement, (along with bilingual fluency in English and Spanish), positions her as a powerful bridge between deep tech and developer outreach.

Valentina Rivas — Technical Writer

Valentina Rivas is a security and blockchain researcher, software engineer, and technical writer with a proven track record of delivering high-impact research and developer-focused content. She specializes in blockchain research, applied cryptography, and blockchain data analytics across the EVM and Solana ecosystems. Her portfolio includes technical coding tutorials for Cyfrin, deep-dive research and data engineering work for The Rollup (covering tokenized assets, stablecoin dynamics, cryptography adoption, etc), and hands-on cryptography tools such as BLS Lab, which demystifies BLS signatures, Shamir’s Secret Sharing, and hashing for developers and non-technical audiences alike. Her tutorials have been officially featured on Ethereum’s Developer Tutorials website section, and her research + coding guides have been cited in U.S. public policy letters.

Valentina also serves as Developer Relations Guild Lead at Myosin, helping shape the guild’s strategy and initiatives for technical content and community growth. With multiple hackathon wins, analytics bounties, and top-ranked dashboards under her belt, Valentina blends technical rigor with accessible communication. She is fluent in English and Spanish, experienced in Solidity, Python, JavaScript/TypeScript, SQL, and advanced analytics platforms, helping organizations strengthen their security posture, improve developer experience, and communicate complex blockchain concepts with clarity.

Romulo Castilho - Creative Director (Project Sponsor)

  • Myosin Design Guild Lead, Ex FutureBrand, and Design Bridge Creative Director

  • Previous Clients: Polygon, XRP, NEAR, Animoca, Google (Asia), Nestlé, Chope (APAC), Bukalapak (Indonesia)


:money_with_wings: Pricing & Payment Terms

$25k flat fee for project completion, which includes;

  • Full documentation audit and strategy development

  • Information architecture redesign

  • Content rewriting for top 1-2 stakeholder groups

  • Implementation in current docs stack

  • Governance framework and workflows

  • Weekly progress updates and stakeholder alignment

  • Includes up to 3 feedback rounds per deliverable

  • Scope beyond this can be scoped separately

Payment Terms:

  • NET 15

  • Initial deposit (30%) invoiced at start of project

  • Open to payment schedule aligned with milestones

Important notes

  • Assumptions & dependencies: Assumes stable APIs/SDKs and provisioned test credentials. If blocking bugs are found, timelines pause until fixes are available.

  • Client-side responsiveness: Our ability to hit timelines depends on prompt feedback from Client. If a document is sent for review and it takes 1–2 weeks to respond, the project will stall. The same applies to technical questions (API/SDK/core concepts), quick answers are key to our speed. We’ll clearly communicate what we need and when we need it to avoid bottlenecks.

  • Partner docs: We will not author or host partner API docs. We provide audits, standards, and link-outs; partners implement changes on their sites.

  • Gateways: By default we do not link to gateways that haven’t met Docs Standards. If the Foundation prefers to link anyway, we can include a disclaimer badge (“Docs in progress”/”Pending updates”) per gateway. We provide their scorecard/summary and must‑fix recommendations.

Optional Add Ons

Custom Video Tutorials - $5,000 Development of 5 professional tutorial videos to complement written documentation. These could be interactive discussions or single person dev rel reviews, uploadable to your chosen social channels.

AI-First Content Development - $5,000 Our approach centers on creating documentation that’s not only human-readable but optimized for AI consumption. We’ll implement semantic headings, structured metadata, and machine-readable references throughout. By integrating natural language search capabilities and ensuring content is properly structured for LLM parsing, we’ll create a documentation system that leverages the latest in AI technology to enhance user experience.

Attribution reporting - TBD Generate reporting to show traffic Livepeer Foundation is delivering to its Gateway Partner docs websites.


:folded_hands: Next Steps

  1. Await Livepeer Foundation decision (available for further qualifying calls if needed)

  2. Finalize contract and scope of work

  3. Begin stakeholder interviews and documentation audit


:red_question_mark: About Myosin.xyz

What is Myosin.xyz, and why are they so good at what they do?


Myosin.xyz is a web3 native marketing network, made of 60+ members across 26 countries.

As a cooperative (some might say DAO), we unite the best marketers from around the world to provide full-stack marketing services to onchain companies & blockchains such as Ripple, NEAR, Starknet, Solana Mobile, Chainbase, POKT Network, Animoca Brands, Rootstock Labs, and many more.

We have 5 core offerings:

  • GTM & Growth

  • PR and KOLs

  • Brand design, video, animations, 3D, & creative

  • Community, social media, content, & research reports

  • DevRel and technical writing

Myosin’s mission is to become an aggregator of the world’s most innovative marketing tactics, and our community of highly vetted talent consists of strategists, creatives, deal makers, developers, growth hackers, and more, all of whom are dedicated to accelerating the adoption of the new internet.

1 Like

My name is Abdur-Rahman Akinkunmi Raji, I am a Technical Writer, while I work independently as a Freelancer, I have hands on deck experience spanning over 36 Months.

Let me know if there’s anyway possible I can contribute to this. Gracias!

Unable to post links here

Livepeer Documentation Restructure Proposal - Delegators Documentation Specialization

Executive Summary

I propose focusing on optimizing the Delegators documentation experience at an accessible $5,000 investment by leveraging my technical writing skills and beginner-friendly perspective to create intuitive, easy-to-follow guides for Livepeer delegators. Great documentation should enable users to understand core value propositions within 5 minutes and complete their first delegation successfully.

Why I’m the Right Fit for Delegators Documentation

Unique Value Proposition

  • Technical Writing Expertise: Specialized in transforming complex concepts into user-friendly content

  • Beginner Empathy: Coming from a non-technical background, I deeply understand newcomers’ pain points

  • Visual Communication Skills: Enhance understanding through diagrams and flowcharts

  • SEO Optimization Experience: Ensure documentation discoverability and search friendliness

Specific Value for Delegators Documentation

As a new Livepeer user myself, I can:

  • Identify hidden cognitive barriers in existing documentation

  • Design learning paths that match beginners’ mental models

  • Simplify staking and reward mechanisms through visual explanations

Specialized Delivery Plan

Milestone 1: User Experience Audit (By October 17) - $1,500

Deliverable: Delegators Journey Analysis Report

  • Pain point mapping of current documentation

  • Comparative analysis with competitor staking documentation

  • Content restructuring plan based on user journey mapping

Milestone 2: Content Restructure (By November 7) - $2,500

Deliverable: Delegators-Focused Documentation Suite

  • Simplified 5-minute quick start guide

  • Visual reward calculation explanations

  • Risk management and best practices guide

  • Interactive FAQ section

Milestone 3: Sustainable Optimization Framework (By December 5) - $1,000

Deliverable: Community Contribution Workflow

  • Delegators documentation maintenance guide

  • Feedback collection and iteration process

  • Multilingual expansion preparation

Why This Focused Approach Makes Sense

  1. Reduced Project Risk: Concentrated scope ensures high-quality delivery

  2. Pilot Value: Successful model can be replicated for other user groups

  3. Optimal Skill Utilization: Technical writing + UX design + beginner perspective

Optional Ongoing Support (Post-Project)

  • Documentation maintenance & updates: $300/month

  • Quarterly UX optimization reviews: $800/quarter

  • Analytics monitoring & improvement: $200/month

Relevant Experience

  • Zero-Knowledge Proof Documentation Rewrite: Learned ZKP from scratch and rewrote technical documentation

  • Technical Content Visualization: Habitual use of diagrams to simplify complex concepts

  • Open Source Community Participation: Active contributor to documentation improvements

Commitment

I will transform Delegators documentation into an onboarding exemplar for the Livepeer ecosystem, enabling every new user to easily understand and participate in network growth.


Looking forward to contributing to Livepeer community’s documentation quality! :slight_smile:

1 Like

Hi everyone,

We’ve submitted a proposal to restructure and modernize Livepeer’s documentation. The plan focuses on creating a clear, AI-ready, stakeholder-focused, and maintainable single source of truth, with guidance for developers, orchestrators, delegators, and gateway operators.

You can review the full proposal here: Notion

We’d love to hear your feedback, suggestions, or questions as we aim to make Livepeer docs more intuitive, up-to-date, and community-friendly.

Thanks,
BuildUnion Team

We propose a complete restructuring and modernization of the Livepeer documentation to create an AI-first, stakeholder-focused, and future-proofed knowledge system. As long-time participants in the Livepeer builder ecosystem and committed “Livepeer maxis,” we understand the product, the community, and the technical foundations of transcoding and AI inference.

Our proposal directly addresses the challenges of Livepeer’s current documentation: complicated onboarding, outdated and duplicated content, poor integration across properties, and lack of AI-first structure. The outcome will be a single-source-of-truth documentation platform that simplifies stakeholder onboarding (developers, delegators, orchestrators, and gateway operators), cleanly separates AI vs. Transcoding workflows, integrates natural-language AI search, consolidates changelogs, and establishes a sustainable governance and contribution process.

Our Livepeer RFP is live below.

Livepeer RFP

Hi all, a big thank you to everyone who has put forward a proposal. We have reviewed all proposals, and have reached a final two in the decision-making process.

To ensure that we make the best choice, we have decided to delay the decision and announcement until Monday. Thanks in advance for your patience and have a great weekend :folded_hands:

1 Like

Hi folks, thanks for your patience, super excited to say that we have made the decision for the Documentation RFP.

After much deliberation, we have decided to proceed with @Wonderland based on her seniority as a Founder of a leading deAI company and senior Dev Rel at Filecoin Foundation, experience in both AI & decentralised Infra at IBM, Accenture and the University of Sydney and her proven ability to project manage complex technical builds.

Given the current state and complexity of our docs, this project is a huge undertaking over the next months with a huge number of different stakeholders. She will be working with the LF, gateways (Daydream, Streamplace, Frameworks, Cloud) and contrbiutors from the AI / Agents SPE and its key that move forward in a community-first way.

We have already kicked off the project. If you have any ideas, comments or concerns, I welcome you reaching out directly to Ally. She will aim to present an RFC on an updated strategy within 2-3 weeks, so the next couple of weeks are crucial.

Thanks to everyone who submitted proposals, as it was a particularly tough decision. A very warm welcome Ali! Let’s clean up some docs :fire:

3 Likes

Hello all!

Thank you for welcoming me at today’s Watercooler Chat [Slides here] where I provided a few key Documentation updates, which I’m also sharing below.

Sharing the latest structured update on the Livepeer Documentation Restructure, aligned with the RFP goals outlined here: RFP — Documentation Restructure - #10 by honestly_rich

Summary - Documentation Requirements

Key points

  • Stakeholder‑focused documentation.

  • AI‑first, LLM‑readable structure.

  • Ecosystem‑integrated resources.

  • Single‑source‑of‑truth documentation

:alarm_clock: Timeline of Work

To complete this work, the project was structured into 4 main phases*.* These phases move from analysis → stakeholder engagement → rebuild & rewrite → automation and AI.

  1. [complete] Phase 1: Foundational Audit, IA, Deprecations
  2. [complete] Phase 2: Stakeholder Alignment & Feedback (NB: stakeholder engagement remains active and welcome)
  3. [now] Phase 3: IA Implementation, Priority Rewrites, Site Integration
  4. [next] Phase 4: Automations, AI Features, Processes

Phase 1: :clipboard: Audit & Analysis

Completed deliverables

  • Content inventory

  • Pain Point & Solution Map

  • Deprecation/Migration matrix

  • Persona journeys

  • Stakeholder mapping

  • IA framework options & recommendations

  • AI Feature Analysis

Direct findings:

  • Livepeer documentation is heavily fragmented across Studio, Cloud, Network, Orchestrators, Delegators and Gateway docs.

  • Significant duplication between Studio guides and developer guides.

  • Critical onboarding paths lack clarity - especially Gateway onboarding, Orchestrator setup, and differentiating Studio vs Cloud.

  • Developers frequently land in the wrong section due to the slider navigation.

  • Many pages are outdated, referencing deprecated features or dead links.

  • IA does not map to Personas; pathways do not reflect real user journeys.

Core Requirements Identified:

  • Fix outdated, contradictory, fragmented content.

  • Create a persona-led information architecture.

  • Remove duplicate Studio/Cloud/Network docs.

  • Integrate enterprise pathways (Gateways, Daydream, BYOC).

  • Define clear ownership and governance over the docs’ content.

Phase 2: :handshake: Stakeholder Engagement

Completed deliverables

  • Stakeholder and community feedback collected through analysis of forum & discord posts as well as stakeholder feedback via meetings & feedback form

  • Feedback consolidation completed.

  • Watercooler update delivered on 25 November.

  • Persona requirement insights fed into IA.

  • IA drafted for review

:information_source: NB: Feedback & Engagement remains ongoing throughout the process!

Please reach out if you’d like to contribute, or share your thoughts in this feedback form :memo:

Feedback Summary

  • Paths confusing (AI vs Video vs Studio; protocol vs product; network vs app).

  • Key technical info missing (orchestrators, LPT/governance, gateways, protocol docs).

  • Need real, runnable examples + full workflows (AI, BYOC, streaming).

  • Structure inconsistent → want unified API + consistent workflows.

  • Governance unclear → need provenance, ownership, contributor paths.

  • Roles unclear → want simple responsibilities + decision flows.

Selected Feedback Quotes

Recommendations

  • Add Builder / Partner / Project HUBs with easy contribution flows.

  • Streamline homepage with clear entry points and zero→hero onboarding.

  • Automate content updates (Luma, gateways, repos, forum/Discord ingestion).

  • Build unified API surface + cross-linked stack (protocol ↔ gateway ↔ orchestrator ↔ product).

  • Create full orchestrator + gateway guides (job types, pipelines, governance).

  • Add dedicated governance/delegator layer (decision trees, safety, fees).

  • Add AI-first features (AI assistant routing, LLM-ready pages, metadata).

[Now] Phase 3: :writing_hand: IA Implementation & Rewrites

Active tasks:

  • IA finalisation and styling

  • Rewriting core sections (Home, About, Community, Protocol)

  • Aggregating ecosystem resources & reaching out to key contributors

  • Building Builder Hub, Project Hub, Contacts page, Resources page

  • Migration guides and deprecation workflows identified

  • AI‑first metadata and semantic markup

  • External doc mapping (Gateways, SPEs, Projects)

Tasks still queued:

  • Protocol, Gateway, Orchestrator, Developer technical deep dives

  • Migration tables and before/after guides

  • Error‑path quickstarts (AI + Video)

[Next] Phase 4: :robot: Automations, Pipelines & AI

Upcoming tasks:

  • Community contribution pipelines

  • External docs auto‑sync (Luma, Gateway resources)

  • Social links automation

  • AI search + AI assistant customisation

  • Multilingual readiness

  • SEO analytics and canonical processes

Thankyou!

Happy to answer questions or walk through the full IA and rewrite the roadmap - and thanks to everyone across the Foundation, Livepeer Inc., Daydream, Streamplace and the broader community who contributed during Phases 1 and 2.

8 Likes

Note: I will share a live link at the end of the week for community review

:blue_book: Documentation Restructure – Project Update

Hi everyone! Happy 2026! :partying_face:

Sharing a more complete update following the original Documentation Restructure RFP and the subsequent updates in Q4.

Over the past period, I’ve been working through a broad restructure of the Livepeer documentation, with a focus on making it more usable day-to-day for builders, operators, and community members - and easier to maintain as the protocol and products evolve. I’ve particularly been focused on making data accurate, up-to-date, easily referenced & digested by AI’s and a canonical HUB for projects, tooling and builders to add to with automations.

You can follow along with the progress in this Github PR in real time (I welcome your feedback!)


:sparkles: What’s Changed

Easier onboarding

The docs now emphasise clearer entry points and more intentional learning paths. Setup flows have been simplified, repetition reduced, and related concepts grouped so new users can move from “getting something running” to understanding how things fit together without jumping across unrelated pages.

Component & layout homogenisation

Documentation now uses a consistent set of shared components and layouts. This improves readability, reduces cognitive load while navigating, and makes future updates less fragile by avoiding one-off page patterns. It also makes community contribution easier (guide coming soon).

More structured, data-driven content

Where appropriate, content is now backed by structured data instead of static text. This helps keep references accurate over time and reduces the risk of documentation quietly drifting out of sync.

Community & Builder hub automations

The Community and Builder sections now rely more on lightweight automation to surface forum posts, blog content, and external references. The goal is to keep these hubs current without constant manual upkeep as well as to create easy pathways for community to contribute and share their tool, projects & docs.

Clearer reference documentation

API and protocol-level reference material is now more clearly separated from guides and conceptual content, making it easier to either quickly look something up or take the time to understand how something works.


:compass: Focus Areas

Newcomers, product discussion, and community

A core goal of this restructure is to better support people who are new to Livepeer - not just at the technical level, but in understanding what the network is, what problems it’s good at, and where to engage. More space has been created for product-level explanation, ecosystem context, and community-facing content so newcomers don’t have to infer intent purely from low-level technical docs.

The Community sections are designed to surface relevant discussions, updates, and examples more naturally, helping people move from curiosity to participation.

Clearer builder & developer documentation

Builder and developer docs are now more explicitly structured around workflows and use cases. Conceptual explanations, guides, and reference material are more clearly separated, making it easier to either learn progressively or jump straight to implementation details.

The intent here is clarity over cleverness: fewer assumptions about prior knowledge, clearer language around roles and responsibilities, and documentation that supports both experimentation and production use.


:loudspeaker: Documentation PR Stats

PR #730 represents 830 file changes & introduces systematic improvements across all documentation areas.

:bullseye: Easier User Onboarding

  • Streamlined Installation Guides: New automated release tracking ensures users always get the latest version

  • Interactive Setup Components: Custom dropdown components for platform-specific instructions (Docker, Linux, Mac, Windows)

  • Automations: Automations that keep content current and enable easier community contributions

  • AI: Deep focus on AI & LLM searches, queries, integrations and discoverability of accurate information


:building_construction: Component & Layout Homogenization

All documentation now uses consistent, reusable components:

New Component Library (snippets/components/):

  • custom-view-dropdown.jsx - Platform/environment switchers

  • cards.jsx - Blog posts, forum posts, and content cards

  • code. jsx - Standardized code examples with placeholder support

  • chainlist.jsx - Live blockchain RPC endpoint fetching

  • coingecko.jsx - Real-time exchange data

  • buttons.jsx, divider.jsx, embed.jsx - UI consistency

Benefits:

  • Consistent visual language across all docs

  • Easier maintenance (update once, apply everywhere)

  • Easier community additions


:bar_chart: Data Integration & Automation

New automated data fetching eliminates stale content:

Forum Integration (automationData/forum/):

  • Live forum post fetching

  • Automatic reply counts and dates

  • Rich preview cards

Blog Integration (automationData/blog/):

  • Ghost CMS data fetching

  • Reading time estimates

  • Author attribution

  • Scrollable post previews

GitHub Release Tracking (automationData/globals/):

  • Auto-updates to latest Livepeer version (v0.8.8 currently)

  • n8n workflow for continuous monitoring

  • Eliminates manual version updates

Real-time External Data:

  • CoinGecko API for exchange listings

  • Chainlist API for RPC endpoints


:robot: Community & Builder Hub Automations

Community Hub Features:

  • Automated forum post cards with live data

  • Rich media support (images, videos)

  • Scroll hints for long content

Builder Resources:

  • External repository embeds with syntax highlighting

  • GitHub integration for live examples

  • Automated API reference generation

  • Custom workflow examples

Example: Forum posts now display with live reply counts, dates, and author info—all fetched automatically. Github md files update in the docs as the reference does.


:books: Full Reference Docs

Complete API Documentation:

  • Gateway API (gateway.openapi.yaml)

  • AI Worker API (ai/worker/api/openapi.yaml) with full pipeline specs

  • OpenAPI specs for SDK generation

  • Full configuration flag explanations

Developer Resources:

  • Structured navigation in docs. json (3,274 lines)

  • Copilot instructions for AI-assisted development

  • Automated script documentation

Technical Improvements:

  • Accurate guides for Gateways & Orchestrators

  • Delegator and governance information


:wrench: Infrastructure Improvements

Build System:

  • Mintlify v2 config (docs. json replaces mint.json)

  • Docker support with Makefile

  • CI/CD ready with GitHub Actions support

  • .gitignore expanded for cleaner repo

Documentation Management:

  • README with clear setup instructions

  • README_V2.md with architecture details

  • SEO optimization guidance

  • Custom 404 support preparation

Scripts (v2/scripts/):

  • generate-api-docs.sh - Auto-generate API docs from OpenAPI

  • fetch-openapi-specs.sh - Sync specs from external repos

  • Automation for data fetching


:memo: Content Organization

The restructure includes:

  • Versioning: Clear v1 (legacy) vs v2 (current) separation

  • Mintlify Migration: Old config preserved as mintOld.json

  • Asset Management: Organized images, logos, static assets

  • External Docs: Fetched at build time, never stale


:rocket: What This Means

  1. For New Users: Onboarding is easier and clearer

  2. For Developers: Always-current API docs with live examples

  3. For Community: Rich, engaging content with automated updates

  4. For Contributors: Consistent patterns make contributions easier


:link: Important Links


:tada: Next Steps

  • Continuing the core work on accurate development guides for gateways, orchestrators and delegators.
2 Likes

Public View Page for Docs-v2

I’ve released a docs public link so the community can contribute and have their say on the progress.

Feedback Requested

Please leave any feedback in this quick form!

Help Wanted!

Want to contribute? (YAY!)

Check out the issues section of this github repo for docs-v2 tagged issues or submit your own / fork these docs (fork branch docs-v2-preview) or get in touch with me!

All sorts of requests from front end and styling cleanups to deeply knowledgeable support and requests for references and guides from stakeholders across the ecosystem would be appreicated!

Big thanks to codewithzubair who’s already contributing! :heart_hands:

3 Likes

Hi @Wonderland friendly reminder that we’re at end of month! I’ll be publishing the cannon report for April next week and sharing it in watercooler. If you’d like your retro or monthly update to be included, feel free to drop it under your original post before then :folded_hands:

Livepeer Documentation v2 is Live

Hello to the Livepeer community.

The v2 documentation overhaul is live at docs.livepeer.org, against the brief in Documentation Restructure RFP. Multilingual translations are in pipeline.

This post covers what shipped, the design philosophy that guided it, and the systems that keep it self-maintaining. It is long because the surface is large. Skim the headings.

What v2 actually is

v2 is not a rewrite. It is a documentation operating system.

The previous site was a Mintlify instance with hand-maintained pages. The new site is the same Mintlify instance sitting on top of a governance layer of 366 governed scripts, 49 GitHub Actions workflows, a unified contributor CLI, a generated component library, an AI agent toolchain, and a manifest-driven self-validating governance contract.

The brief asked for stakeholder-focused, AI-first, future-proofed docs. We treated that as three product requirements and built the infrastructure each one needed.

Three principles that drove every decision

1. Documentation is not static. It is infrastructure.

Editorial output degrades. Infrastructure is maintained under load, tested, versioned, and governed. Every script, every hook, every workflow in this repo exists to make the documentation behave like infrastructure rather than like a website that someone has to remember to update.

2. AI is the new search.

For a decade, SEO was the discoverability lever. That is being displaced. Developers begin product research with ChatGPT, Claude, Perplexity, or Gemini. Documentation is now read, evaluated, and cited by machines before it reaches humans.

This shifts what “good docs” means. Semantic headings, stable canonical URLs, machine-readable frontmatter, OpenAPI integration, AEO (Answer Engine Optimization), AI-integrated pipelines, and llms.txt are no longer nice to have. They are the new minimum viable distribution layer.

3. Agents are the new docs consumers.

The next wave is automated systems that query docs to generate code, configure infrastructure, or build integrations. These agents need pages with explicit preconditions, invariants, verification steps, and failure modes. The repo serves agents alongside humans on equal terms.

The page at /v2/gateways/quickstart/AI-prompt is a direct instantiation. It is written for AI agents, not human reading.

These three principles are codified at docs.livepeer.org/v2/internal/overview/docs-philosophy.

The D.O.C.S. System™

The strategic operating model that frames the whole engagement:

  • Distribution Infrastructure

  • Operational Governance

  • Composable Execution

  • Signal & System Feedback

Below is what each of those looks like as concrete repo surfaces.


Stakeholder portals: the human-facing surface

Every persona has a zero-to-hero journey. No-one should need Discord intervention to get started.

Each portal lands on a frame-mode hero, routes to start-here cards and key-path cards, then opens into structured tutorials, how-tos, references, and explanations following the Diátaxis framework.

Ownerless governance: the design philosophy that makes it sustainable

This is the bit that matters most for sustainability.

Most documentation projects rot because they depend on a standing human owner to interpret failures, route fixes, and approve repairs. The moment that person rotates off, drift starts.

This repo is built so that no governed surface depends on a standing human owner.

Every governed surface in the repo must declare four things:

  1. One canonical source. The file or path that defines truth.

  2. One deterministic validator. A script that detects drift.

  3. One exact repair path. A repo-backed command that any contributor or AI agent can run directly.

  4. One primary gate layer. Either pre-commit, PR-changed, scheduled, or manual.

If any of those is missing, the surface is not ownerless-ready and stays advisory.

The contributor loop is then mechanical: change the canonical source, run the validator, read the exact repair output, run the repair command, re-run the validator, merge once green. No private context required. No DM to a maintainer required. Available to OSS contributors and AI agents on equal terms.

The full contract lives at docs.livepeer.org/docs-guide/policies/ownerless-governance. The machine-readable manifest is at operations/governance/config/ownerless-governance-surfaces.json.

Rollout states are advisory, autofix, blocking, or migrating. Promotion to blocking requires a clean baseline run, changed-file PR simulation, and exact repair output for every blocking failure mode.

Infrastructure first principles: the gate-layer model

Five tenets:

  1. Single responsibility per layer. Each gate owns one class of risk.

  2. Fast local feedback. Pre-commit is local, offline, and bounded under 60 seconds.

  3. Governance at branch and CI boundaries. Contract checks run at pre-push and CI.

  4. One canonical policy source. Operational docs link, not copy.

  5. Measurable SLOs. Runtime budgets are enforced, not aspirational.

Severity is graded P0 (merge/deploy safety), P1 (correctness/governance), P2 (quality drift), P3 (advisory debt).

Every check declares its primary gate layer. Pre-commit owns staged structure and style. Pre-push owns codex contract and issue readiness. PR CI owns blocking changed-file checks. Full sweeps own browser, link, OpenAPI, and WCAG checks.

Contract is at docs.livepeer.org/docs-guide/policies/infrastructure-principles.


The lpd CLI: one command surface for the entire system

Contributors interact with the docs operating system through a single CLI: lpd.

lpd standardises every contributor workflow:

lpd setup       # bootstrap dependencies, hooks, optional PATH install, Codex skill sync
lpd doctor      # check repo readiness, dependencies, Mint, hook state
lpd dev         # local Mint dev server, scoped or full
lpd test        # staged or full tests, browser, domain, WCAG, external link audits
lpd ci          # local CI-like validation
lpd move-page   # governed page move with docs.json sync
lpd ai-sitemap  # generate or validate sitemap-ai.xml
lpd hooks       # install, status, verify, run .githooks scripts
lpd scripts     # list and run any of the 366 governed scripts by group

lpd dev defaults to port 3333. Scoped mode lets you run Mint against a single tab, version, language, or route prefix:

lpd dev --scoped --scope-tab Developers
lpd dev --scoped --scope-prefix v2/orchestrators
lpd dev --scoped --docs-config docs-orch-work.json

Tab matching is fuzzy. Resources resolves to Resource HUB, Orch resolves to Orchestrators, LP resolves to LP Token. Scope inputs are validated before any setup work runs so bad tab names fail immediately.

lpd scripts run exposes the full governed script library by group: tools, tasks, tests, v2, hooks. Risk is graded low for tests, medium for tools and hooks, high for tasks and v2. High-risk groups prompt for confirmation unless --yes is supplied.

Every command supports a JSON envelope for agent and CI consumption: { ok, command, message, exit_code, repo_root }.

Reference at docs.livepeer.org/docs-guide/tooling/lpd-cli.


What the 366 scripts actually do

The catalog at docs.livepeer.org/docs-guide/catalog/scripts-catalog is generated from the JSDoc headers of every script. It groups scripts by type and names every pipeline gate they belong to.

Top-level types:

  • Audits – component usage, copy patterns, glossary gaps, icon usage, media assets, script categories, tasks folders, v2 usefulness, content freshness, page research, terminology coverage

  • Generators – AI sitemap, llms.txt, OG images, SEO, glossary companions, component registry, component docs, UI templates, docs index, repo governance map, root governance artifacts, script registry, snippets registry, AI tools registry artifacts

  • Validators – page imports, page links, anchor usage, MDX safety, frontmatter taxonomy, description quality, double headers, page endings, component docs, component CSS, component health, component immutability, naming conventions, MDX component scope, EN-GB grammar, proper nouns, governance approvals, repo governance sync, root governance sync, codex task contract, codex locks, OpenAPI reference, page rendering, agent docs freshness, AI tools registry coverage

  • Remediators – page imports, page links, MDX-safe markdown, ownerless language, spelling, docs paths, Mintlify canonical consumers, component metadata, asset migration to branch, JSDoc headers, framework headers, page-type assignment, purpose metadata, SEO generation, WCAG common fixes, callout insertion

  • Dispatchers – page integrity dispatch, governance pipeline orchestration, repo audit orchestrator, sync generated files, run-all, run-pr-checks, headless batch executor, session state, cross-agent packager, post-merge sync

  • Library modules – 57 internal shared modules covering MDX parsing, frontmatter, providers, scoring, glossary, journey checking, file walking, generated artifact policy, Mintignore handling, path utilities, repo governance, root governance, scoped docs config resolution

Pipeline phases are explicit. P1 commit gate (49 scripts), P2 push gate (13 scripts), P3 PR gate (45 scripts), P5/P6 scheduled (16 scripts).

Auto-remediation: the repair surface

This is where docs-as-infrastructure stops being a slogan.

When a validator finds drift, it does not just report. It points to a repair command that any contributor or agent can run.

Concrete examples:

  • repair-mdx-safe-markdown.js rewrites deterministic MDX-unsafe patterns

  • repair-page-imports.js removes safe unused page-reachable React runtime imports

  • repair-page-links.js rewrites safe relative internal href literals to canonical root-level routes

  • repair-spelling.js applies cspell-driven safe corrections

  • style-and-language-homogenizer-en-gb.js and the EN-GB grammar checker fix US-to-UK spelling and approved style guide drift

  • repair-ownerless-language.js removes human-owner dependencies from governed surfaces

  • repair-component-metadata.js auto-repairs derived JSDoc metadata fields from repo state

  • sync-docs-paths.js applies governed docs.json and reference rewrites for moved pages

  • sync-mintlify-canonical-consumers.js applies canonical-path rewrites for registered consumers

  • quarantine-manager.js classifies and (with --apply) moves files to safe quarantine paths

  • migrate-assets-to-branch.js migrates flagged assets to docs-v2-assets and rewrites references to raw GitHub URLs

  • wcag-repair-common.js applies conservative WCAG source autofixes for common raw-tag issues

  • governance-pipeline.js chains audit, safe repair, verification, and reporting into a single self-healing pipeline

  • The OpenAPI reference workflow autofixes method case, METHOD/path spacing, and leading slash in non-PR runs

Every remediator is dual-mode: --check to detect, --write to apply. Most are wired into pre-commit or scheduled CI so drift gets corrected automatically where deterministic.

Unresolved findings are tracked through rolling marker issues with idempotent labels (docs-v2, help wanted, status: needs-routing, type: bug, area: ci-cd). Clean runs close the issue with a resolution comment.

Generated artifacts: the parts that maintain themselves

Generated files are rebuilt from source, never hand-edited. They carry an enforced banner, validated by enforce-generated-file-banners.js. Any drift between the canonical source and the derived output is detected and repaired by sync-generated-files.js.

Generated surfaces include:

  • docs-index.json – the route and frontmatter index, the most-called artifact in the repo

  • sitemap-ai.xml – AI-optimised sitemap, generated by generate-ai-sitemap.js, refreshed on schedule

  • llms.txt – AI-first root contract, generated from docs navigation

  • docs-guide/catalog/components-catalog.mdx – the component inventory

  • docs-guide/catalog/scripts-catalog.mdx – the 366-script inventory itself

  • docs-guide/catalog/pages-catalog.mdx – the v2 page inventory

  • docs-guide/catalog/workflows-catalog.mdx – the GitHub Actions inventory

  • docs-guide/catalog/templates-catalog.mdx – the UI template inventory

  • tools/config/registry/script-registry.json – derived from JSDoc across all governed scripts

  • .vscode/templates.code-snippets and .vscode/components.code-snippets – authoring snippets

Generated artefact policy is at docs.livepeer.org/docs-guide/policies/generated-artifact-and-hook-governance.


AI features at three levels

Reader assistants

The Mintlify AI assistant is built into docs.livepeer.org. It uses agentic RAG with tool-calling against the published docs. Conversation analytics surface unanswered questions as content gap signals.

llms.txt is governed as an AI-first public root artefact, generated from the navigation by operations/scripts/generators/ai/llm/generate-llms-files.js.

The Mintlify-hosted MCP server lets Claude, Cursor, Windsurf, or any MCP client query the published docs in real time:

npx mcp add livepeer

Agent adapters

AGENTS.md is the baseline instruction set. Every agent reads it first, then loads its native adapter:

Agent Adapter Scope
Claude Code .claude/CLAUDE.md Full project context, session management, co-work skills
Cursor .cursor/rules/ Governance rules, deletion guards
Windsurf .windsurf/rules/ Governance rules
GitHub Copilot .github/copilot-instructions.md Inline code suggestions
Augment Code .augment/rules/ Governance, git safety, deletion guards
Codex .github/AGENTS.md Task isolation, checkpoints, lock contracts

Codex branch contract

AI agent implementation branches use codex/<issue-id>-<slug> naming. These branches are hook-enforced with a task contract file at .codex/task-contract.yaml, pre-push validation, and templated PR body generation by create-codex-pr.js.

28 AI skills

Skills provide structured workflows for both humans and agents. Invoke with /skill-name in Claude Code.

  • 9 co-work and process skills: /thread, /pm, /research, /design, /build, /iterate, /dispatch, /agent-brief, /diagnose

  • 4 content-pipeline skills: pass A, pass B, tab map, page authoring

  • 8 audit and governance skills: repo audit orchestrator, docs coverage, docs quality and freshness, script footprint, component layout, generated banners, cleanup quarantine, cross-agent packaging

  • 7 review and specialised skills: review packet generation, fix execution, rubric static review, copy editing, EN-GB style, product thinking, skill docs

10 portable templates live in ai-tools/ai-skills/templates/ and sync to Codex via sync-codex-skills.js or bash tools/lpd setup --yes.

Skills chain in a standard workflow: /thread (anchor), /pm (plan), /research (investigate), /design (architect), /build (execute), /iterate (review).

AI-powered pipelines

  • Glossary companion generation: extracts SearchTable item lists from MDX glossary pages and writes companion JSON for AI and crawler discoverability

  • Content health automation: weekly scheduled scan for stale pages, broken links, and content drift, with reports under workspace/reports/

  • Language translation: OpenRouter-driven pipeline for multi-locale content, with frontmatter taxonomy validation enforcing valid locale values

Reference at docs.livepeer.org/docs-guide/features/ai-features.

Claude Code hooks

The repo ships native Claude Code hook integrations covering PreToolUse (destructive git block, public-post block, unconfirmed-write block), PostToolUse (Edit/Write blast-radius scanner, MDX validation, Bash move-detect, Read logger, phase-gate), UserPromptSubmit (MDX-constraints injection, message backup, friction logger), and PreCompact (checkpoint), plus session register and session state.


UI system: governed components and template scaffolding

Components live in snippets/components/ under JSDoc-driven governance. Validators enforce JSDoc coverage, prop documentation, CSS variable rules, file naming, PascalCase exports, MDX-facing scope, and component immutability in PR context.

The component inventory at docs.livepeer.org/docs-guide/catalog/components-catalog is generated from the registry.

Templates are governed and generated. Page templates live at snippets/templates/pages/** and produce one direct preview route each:

  • FAQ page, how-to page, landing-frame page, overview page, reference page, troubleshooting page, tutorial page

  • Landing-and-navigation: navigation page, portal page

  • Reference-and-API: OpenAPI endpoint page

  • Setup-and-code-layouts: multi-view page

Block templates live at snippets/templates/blocks/**: comparison matrix, comparison table, related pages cards, related pages CTA.

Templates auto-generate VS Code snippets at .vscode/templates.code-snippets and .vscode/components.code-snippets via generate-ui-templates.js. Authoring with lp-overview, lp-howto, lp-tutorial, lp-reference, lp-landing-frame, template-faq-page, template-troubleshooting-page, template-openapi-endpoint-page is one keystroke in VS Code.

UI system reference at docs.livepeer.org/docs-guide/features/ui-system.


Automations and live data

Three core pipelines

1. Quality and CI

  • test-suite.yml runs changed-file checks plus browser test

  • test-v2-pages.yml runs the v2 browser sweep with artifacts and PR comments

  • broken-links.yml runs the advisory link checker

  • validator-health-check-openapi-reference.yml runs blocking OpenAPI endpoint integrity checks for v2 plus locales, with conservative autofix on non-PR runs (method case, METHOD/path spacing, leading slash). Failures track through a single rolling marker issue. Clean runs close it.

2. Data refresh

  • audit-health-scan-data-freshness.yml runs the advisory daily freshness report

  • integrator-maintenance-update-release-version.yml updates global release data from update-livepeer-release.js

  • update-forum-data.yml, update-ghost-blog-data.yml, update-youtube-data.yml refresh community feeds

  • integrator-copy-update-showcase-submissions.yml refreshes the showcase pipeline

  • integrator-maintenance-update-config-flags.yml, integrator-maintenance-update-exchanges-data.yml, integrator-maintenance-update-large-assets.yml, integrator-maintenance-update-contract-addresses.yml refresh the rest

3. Governance and intake

  • interface-governance-intake-discord-issues.yml and interface-governance-label-issues.yml handle issue intake

  • interface-governance-assign-reviewers.yml, interface-governance-index-issues.yml, interface-governance-close-linked-issues.yml handle review automation

  • dispatch-governance-post-merge-sync.yml runs post-merge sync

  • validator-governance-check-codex-compliance.yml, validator-governance-check-governance-map.yml, validator-governance-check-workflow-governance.yml enforce governance contracts

Reference at docs.livepeer.org/docs-guide/features/automations.

Live data ingestion

Forum, blog, YouTube, GitHub Releases, GitHub Discussions, Discord announcements, Ghost RSS, generic RSS, LPT exchanges, OpenAPI specs, and on-chain contract addresses all flow into the docs through dedicated fetcher scripts.

Ingestion outputs are committed under snippets/data/social-feeds/, snippets/data/globals/, snippets/data/showcase-feed/. The chain-first contracts pipeline pulls verified addresses from on-chain sources and renders them through Playwright-tested reference pages.

n8n pipeline assets live at snippets/assets/data/n8n/. Active pipelines: project showcase application workflow, Showcase project pipeline, Discord announce to Mintlify, Luma to Mintlify. Superseded n8n definitions are mirrored to tasks/staging/deprecated-n8n/ for deprecation tracking.

Data integrations and OpenAPI

Canonical API specs live in api/:

  • api/openapi.yaml and api/openapi.json

  • api/studio.yaml (311 KB)

  • api/gateway.openapi.yaml

  • api/ai-worker.yaml

  • api/cli-http.yaml

Generation helpers fetch-openapi-specs.sh and generate-api-docs.sh regenerate reference pages from the specs. The OpenAPI reference audit runs daily plus on every PR plus on push.

Internal data layers cover route/link maps at snippets/data/*/hrefs.jsx, domain data modules at snippets/data/**/*.jsx, and the AI sitemap at sitemap-ai.xml.

Reference at docs.livepeer.org/docs-guide/features/data-integrations.


Content veracity and research

Content correctness is treated as a first-class governed surface, not a review step.

  • docs-page-research.js extracts factual claims from docs pages, checks evidence sources, and detects contradictions across related pages

  • docs-research-adjudication.js records measured review outcomes so trust decisions are based on real usage

  • docs-research-packet.js derives nav, manifest, or path scope and runs the research stack tranche-by-tranche

  • docs-page-research-pr-report.js runs the fact-check runner on changed docs pages and emits an advisory PR artefact summarising claim families, contradictions, unresolved factual risk, and propagation follow-up

  • audit-v2-usefulness.js scores v2 pages on human and agent usefulness with source-weighted 2026 accuracy verification

  • docs-quality-and-freshness-audit.js checks for TODO/TBD/Coming Soon markers, thin pages, and stale content

  • audit-glossary-gaps.js finds terminology candidates not yet defined

  • generate-content-gap-reconciliation.js compares blueprint coverage against shipped MDX

The quality gate map is at docs.livepeer.org/docs-guide/policies/quality-gates.


Translations

The translation pipeline is wired and operational.

  • translate-docs.js translates v2 MDX pages to target languages via OpenRouter

  • generate-localized-docs-json.js produces locale-specific docs.json from the route map

  • validate-generated.js checks generated MDX and route-map outputs for integrity

  • The Mintlify version and language toggle is wired through the audit at test-mintlify-version-language-toggle.js

  • Frontmatter taxonomy enforcement at frontmatter-taxonomy.js blocks invalid locale values at commit

  • Translation provenance is tracked in provenance.js

Generated locale files carry the same banner enforcement as English originals. The enforce-generated-file-banners.js validator includes i18n parity checks. Live Pioneers and AI-assisted translations flow through the same pipeline.

Workflow at .github/workflows/integrator-copy-update-translations.yml.


Accessibility

The v2 WCAG audit (v2-wcag-audit.js) runs WCAG 2.2 AA conformance checks across docs.json navigation pages with deterministic reports and conservative source autofixes. Common raw-tag issues (iframe titles, img alt, icon-only anchor aria-label) are auto-repaired through wcag-repair-common.js.

lpd test --staged --wcag runs the audit locally on staged files. lpd test --full runs it across the full v2 surface.


Visual Explainer (maintainer pilot)

A pilot Claude Code skill, nicobailon/visual-explainer, is available for maintainers as an out-of-repo tooling layer. It is not in CI, not in Mintlify, not a contributor gate.

Six maintainer use cases:

  1. /plan-review for cross-referencing plan documents against actual codebase

  2. /diff-review for visual review of structural PRs touching docs.json, snippets/components/, .github/workflows/

  3. /generate-web-diagram for rescuing commented-out architecture diagrams (BYOC and Marketplace Interaction Model in v2/gateways/resources/technical/technical-architecture.mdx)

  4. /fact-check for verifying delivery report claims against the codebase

  5. /project-recap for contributor onboarding and maintainer context-switching

  6. Persona routing matrix as an internal artefact

Outputs land in ~/.agent/diagrams/ and stay out of the repo during pilot. 4-week rollout. Reference at docs.livepeer.org/docs-guide/features/visual-explainer-workflows.


Internal hub

The Internal tab at docs.livepeer.org/v2/internal hosts the philosophy, the RFP traceability, the delivery reports, and the operational reports against the brief. This is where stakeholders can audit what was built against what was committed.

It includes:

  • The docs philosophy page citing Diátaxis, Docs as Code, and the D.O.C.S. principles

  • The 21 AI-First Docs items in the AI-First Report

  • Delivery reports, retrospectives, and audit outputs published from the governed report pipeline (publish-v2-internal-reports.js)

  • The full v2 internal reports tree under v2/internal/reports/


How a contributor adds a page today

  1. bash lpd setup --yes once, to install dependencies, hooks, and Codex skill sync

  2. lpd dev --scoped --scope-tab Developers to preview just the Developers tab

  3. In VS Code, type lp-howto (or lp-overview, lp-tutorial, lp-reference) and a fully scaffolded page appears with canonical frontmatter, prerequisites, steps, validation, and a next-step CTA

  4. Write the content

  5. Commit. The pre-commit hook runs tests/run-all.js --staged --skip-browser which validates style, MDX, links, imports, frontmatter, descriptions, double headers, page endings, anchors, naming, generated artefact sync, EN-GB grammar and proper nouns, banned words and patterns, MDX-safe markdown, component scope, and codex task contract if on a codex/ branch. Anything deterministic that drifted is offered an exact repair command.

  6. Push. The pre-push hook runs codex contract and issue-readiness checks.

  7. Open PR. CI runs the changed-file blocking suite plus the broad sweeps. Governance approval labels gate any governance-sensitive PR.

  8. Merge. Post-merge sync runs catalog regeneration, AI sitemap regeneration, OG image regeneration, llms.txt regeneration, and component registry regeneration.

The contributor never has to remember to do any of it.


Why we built it this way

The v2 brief had three asks: stakeholder-focused, AI-first, future-proofed.

Stakeholder-focused without a governance layer means the docs degrade the first time a contributor leaves. AI-first without a generation layer means llms.txt and AI sitemap are stale within a sprint. Future-proofed without ownerless governance means future-proofing depends on a future human who may not exist.

So the answer to all three asks was the same: build the documentation as infrastructure, with deterministic validators, exact repair paths, and gate-layer ownership baked in. Do that, and the rest follows.

The 366 scripts, the 49 workflows, the lpd CLI, the 28 AI skills, the agent adapters, the component library, the auto-remediation surface, the live data ingestion, and the ownerless governance contract are all that answer in concrete form.

The site is live at docs.livepeer.org. Translations are in pipeline.

Thanks to Rick (technical direction and engineering), Rich (executive), j0sh (SDK and remote signers), Peter (AI SPE), Mehrdad (protocol), and the Cloud SPE, Titan Node, and DeFine teams for review cycles. Thanks to the Foundation for backing the brief, and to the community for showing up to help wire it through.

-- Wonderland (docs lead, Livepeer Foundation)

1 Like