Skip to main content

​
Complicated Onboarding

The v1 documentation’s navigation relied on a toggle-based model where all user types entered the same homepage and were expected to self-select their path. In practice, this produced paralysis: new users did not have sufficient context to know which toggle applied to them. The decision point was which structural model would produce the most direct path from “I just heard about Livepeer” to “I am doing the thing I came to do.”Three architectural options were considered. First, a flat tag-based model where content is tagged by persona but lives in a unified hierarchy - rejected because it does not compress navigation decisions; users still had to scan and filter. Second, a job-type-first model (build/operate/stake/reference) - rejected because user interviews confirmed people identify with role identity, not task abstraction. Third, persona-first with Diátaxis typing - selected because it maps directly to how users self-describe (“I’m a developer building on Livepeer”) and allows the documentation to answer the question “where do I start?” before the user has to ask it.
Persona journey maps were produced for all four core types documenting the literal sequence of clicks and decisions a new user makes from landing on docs.livepeer.org through to their first successful action. These maps identified specific friction points: the v1 toggle required users to know the distinction between “developer” and “gateway operator” before they had any context. The v1 Delegator section had minimal content with no interactive delegation walkthrough. The v1 Orchestrator path assumed significant prior knowledge of GPU infrastructure.Forum and Discord crawls identified the most common incoming questions per persona. Orchestrator questions concentrated on node setup and earnings calculation. Developer questions concentrated on SDK choice and API authentication. Delegator questions concentrated on where to go to stake and what the risk was. Gateway operator questions concentrated on when to run self-hosted versus use Studio. These patterns directly informed what content each “entry point” needed to answer immediately.
  • [IA] Nine top-level sections in docs.json, each a direct stakeholder entry point: Home (orientation), About (network understanding), Platforms (product landscape), Developers (builders), Gateways (gateway operators), GPU Nodes (orchestrators), LP Token (delegators), Community (ecosystem), Resource HUB (references). No toggle required.
  • [UI/UX] Homepage “Mission Control” hero with role-selector cards. Each card names the persona, states the primary goal, and links directly to the entry-point page. Visual hierarchy makes the “start here” decision trivial rather than requiring exploration.
  • [UX] Zero-to-hero progression modelled for each persona. Developer path: landing → Platforms overview → developer portal → quickstart → SDK reference. Gateway operator path: landing → Gateways → gateway providers → run a gateway → configuration. Each path is completable without backtracking.
  • [Content] Section-level index pages for each persona section provide orientation summaries, “what you’ll find here,” and quick-links to the most common entry tasks. Replaces the v1 pattern of dumping users into a long flat list.
  • [Copy] All copy is written from the user’s perspective (“you want to…”) rather than the product’s perspective (“Livepeer provides…”). Entry point pages answer the question “is this right for me?” before explaining what to do.
  • [DX] Developer portal separates AI Jobs from Transcoding Jobs with distinct labelled entry points. Cross-cutting resources (SDKs, APIs, CLI) are surfaced as shared references rather than buried within persona sections, so developers do not have to know which persona section “owns” the API reference.
  • [Technical] docs.json navigation structure with numbered prefix system (00_home through 09_internal) provides stable, predictable URL patterns. Sidebar breadcrumb structure is explicit and non-ambiguous. Redirects configured for all v1 URLs to their v2 equivalents, preserving existing bookmarks and links.
  • [Technical] Link checker CI (link-check workflow) prevents new broken links from merging. URL restructure during the v2 deployment caused a temporary regression that is in active remediation - the infrastructure to prevent recurrence is in place.
The AI Jobs and Transcoding Jobs quickstarts - the deepest persona-specific onboarding content - remain in finalisation. These pages exist structurally but require technical input from Peter (AI SPE Lead) and Rick (Technical Director) to complete with accurate pipeline details and verification steps. The entry-point architecture is complete; the terminal destination content is blocked on stakeholder availability.

​
Outdated or Inconsistent Content

Outdated content in v1 fell into four categories requiring distinct responses: deprecated APIs needing removal or migration guides; stale references needing update to current versions; AI coverage gaps needing new content; and changelog fragmentation needing consolidation. Each required a different approach. For deprecated APIs, the decision was between leaving them in place with deprecation banners (lower risk, lower maintenance burden) and removing them with 301 redirects to current alternatives (higher-trust signal, requires redirect infrastructure). Active 301 redirect management was selected as it produces a higher-quality signal for both users and search engines. For fragmented changelogs, the options considered were: a manually maintained single changelog (low automation, high drift risk), an automated aggregation pipeline consuming multiple release feeds (high value, requires each upstream team to maintain a machine-readable feed), and a changelog placeholder page with links to each product’s native changelog (lowest value, but achievable without upstream coordination). The automated approach was designed and partially implemented; full delivery is blocked on upstream teams adopting a shared format.
A page-by-page v1 content audit produced specific recommendations for every existing page: keep, rewrite, move, merge, or deprecate. The Developer docs section was found to be heavily Studio-centric; 12+ pages were recommended for migration to Studio documentation. The AI Video (Beta) section required reviewing 9 AI pipeline pages for deprecation - Rick confirmed most deprecated except text-to-image. A deprecation/migration matrix mapped every legacy page to its v2 destination or deprecation status.
  • [Technical] Deprecation matrix produced and actioned. 12+ Studio-specific pages removed from core docs with 301 redirects to livepeer.studio/docs. v1 preserved at docs.livepeer.org/v1 with version switcher, ensuring no content is lost for existing users.
  • [Technical] 7 deprecated AI pipeline pages removed; text-to-image retained as the one confirmed active pipeline. AI coverage expanded with new gateway AI API reference pages for all current pipelines: audio-to-text, image-to-image, image-to-text, image-to-video, live-video-to-video, LLM, segment-anything-2, text-to-image, text-to-speech, upscale.
  • [Technical] OpenAPI specs integrated for all current APIs: gateway.openapi.yaml, ai-worker.yaml, studio.yaml, openapi.json/yaml. fetch-openapi-specs.sh and generate-api-docs.sh automate spec fetching and documentation generation, reducing the lag between API changes and documentation updates.
  • [Scripts] generate-seo.js enforces current metadata across all pages. Glossary automation (generate-glossary.js) maintains terminology consistency - a common source of inconsistency in v1 where the same concept was described differently across sections.
  • [Automations] Release tracking automation (update-livepeer-release.yml) auto-updates the current Livepeer version globally across all pages that reference it. Eliminates the category of staleness caused by version numbers becoming outdated between manual updates.
  • [Internal docs] docs-guide/features/data-integrations.mdx documents all API specifications, external feeds, and internal data layers - providing a single reference for maintainers to understand what data sources exist and how they are kept current.
  • [Scripts] audit-scripts.js audits the full repository for executable scripts and identifies coverage gaps. The same audit pattern is extensible to content coverage - identifying pages that reference deprecated APIs or stale version numbers.
The canonical changelog is the most significant unresolved gap in this category. No single changelog existed in v1, and the multiple upstream release streams (Studio, AI worker, on-chain network parameters, gateway versions) do not share a common release format. The infrastructure to aggregate and display a unified changelog exists; the upstream content ownership model has not been established. This requires explicit commitment from each product team to maintain a machine-readable release feed. Some pages in the Gateways and Developers sections remain marked WIP or contain TODO placeholders following the URL restructure recovery. These are tracked in the close-out task list and are in active remediation.

​
Brand & Duplication

Brand confusion in v1 arose from a structural issue: Livepeer Studio, an opinionated product built on the Livepeer network, was documented inside the core protocol documentation. This created two problems. Users who wanted to use the network directly were routed through Studio-specific instructions that did not apply to them. And users who wanted to use Studio were not getting the full Studio product documentation, because much of it lived in livepeer.studio/docs.The options considered were: keep Studio in core docs with clearer labelling (lowest disruption, perpetuates confusion); move all Studio content to livepeer.studio/docs and redirect (cleanest separation, requires Studio team coordination); or create a dedicated “Platforms” section in core docs that contextualises Studio alongside other gateway products without hosting Studio’s full operational documentation. The Platforms section model was selected as it solves the brand confusion without requiring Studio to be completely rebuilt, and it positions Livepeer as a multi-product ecosystem rather than Studio-centric.For SDK and API duplication, the decision was to consolidate into single canonical hubs in the Developers section with cross-references from Gateway and AI sections - rather than attempting to maintain parallel copies with eventual synchronisation.
Brand strategy analysis mapped the relationship between Livepeer protocol, Livepeer network, Livepeer Studio, and the gateway ecosystem. This analysis produced the ‘layered system’ framing: Protocol → Network → Product Platform → Ecosystem. This hierarchy resolved the brand confusion by making clear that Studio is a product built on the network, not the network itself. The ‘Using Livepeer Studio as a Gateway’ page makes this relationship explicit and provides the correct entry point for Studio users who need gateway functionality.
[IA] Platforms section created as a dedicated home for all gateway products and ecosystem tools: Livepeer Studio, Daydream, Streamplace, Frameworks - each with its own orientation page that explains the product’s role in the ecosystem, its relationship to the Livepeer network, and where to find full product documentation. [Product Positioning] “Open AI-Infrastructure for Real-Time Interactive Video” positioned as the core docs identity - protocol and network layer - with Studio and other gateway products as implementations. The confusion between “Livepeer the network” and “Livepeer the product” is resolved at the IA level. [Content] 12+ Studio-specific pages removed from core docs with 301 redirects to livepeer.studio/docs. Migration guide for Studio users provides before/after mapping for users who bookmarked Studio content in the old location. [Technical] SDK documentation consolidated into a single Developer SDK hub rather than maintained separately in Developer and AI sections. AI SDK documentation cross-references the canonical hub rather than duplicating content. [Technical] AI gateway API reference pages live in the Gateways section under the canonical API reference structure (gateway.openapi.yaml). No duplication with the Developer SDK docs - cross-references link between them. The source-of-truth policy enforces this: one page owns the content, others reference it. [Internal docs] source-of-truth-policy.md explicitly defines canonical ownership for each content type, preventing future duplication. If a new SDK or API is added, the policy specifies exactly where the canonical documentation lives and how other sections should reference it. [Copy] Voice and tone guide (developed with Joseph, embedded in style-guide.mdx) establishes consistent Livepeer terminology and product naming conventions. “Orchestrator” not “node operator,” “gateway” not “transcoder” (in consumer context), “LP token” not “LPT” in user-facing text. Terminology consistency is enforced via the glossary automation pipeline. [UI/UX] Product HUB page (v2/pages/02_platforms/products/all-ecosystem/product-hub.mdx) provides a filterable, sortable ecosystem overview showing all products and their relationship to the network. Architecture for automation via Google Form → GitHub PR → merge is defined; currently in pre-automation state.
The Studio migration guide’s narrative page - explaining the conceptual shift from Studio-as-docs to Studio-as-product - remains incomplete. Redirects are in place (users who click old Studio URLs are routed correctly), but the explanatory page that helps users understand why the documentation changed has not been written. This is a content gap, not an infrastructure gap.

​
Weak Site Integration

Site integration in documentation can be approached at three levels of ambition.
  • The minimal approach embeds links to external tools at relevant points in the documentation.
  • The intermediate approach builds contextual integration: documentation pages that explain each tool’s purpose and link out with context rather than just a raw URL.
  • The maximal approach creates live data connections: documentation that renders current data from the explorer, governance portal, or dashboard rather than directing users to open a separate tab.
The v2 engagement targeted the intermediate approach as baseline and built toward the maximal approach for high-value surfaces. The Gateway Explorer page, for example, embeds an iframe of the live explorer interface. The LPT exchange data integration pulls live token data. The release tracking automation keeps the “current version” reference live. This is a systematic infrastructure for live data integration, not a documentation-only solution.
Forum and Discord crawl identified the specific tools users expected to find linked from the docs: the Livepeer Explorer (for staking and orchestrator selection), the governance portal (for LPT holders to vote), the Studio dashboard (for developers), and the gateway-specific explorer (for gateway operators).Pain points surfaced: users would read about delegation in the docs and then not know where to actually go to delegate. Users would read about orchestrators but have no quick path to the explorer to evaluate one.
  • [UI/UX] Explorer integration: Livepeer Explorer (explorer.livepeer.org) linked and contextualised across Delegator and Orchestrator sections. Developer tools section includes dedicated Livepeer Explorer page (v2/pages/03_developers/developer-tools/livepeer-explorer.mdx) explaining key functions for each persona: staking and delegation, orchestrator insights, gateway insights, governance, transaction tracking.
  • [UI/UX] Gateway Explorer integration: dedicated page (v2/pages/04_gateways/gateway-tools/explorer.mdx) embedding the live Gateway Data Explorer iframe. Links directly to the gateway-specific explorer interface and the open-source explorer codebase on GitHub.
  • [Technical] LPT exchange data integration: automated fetching of live LPT exchange data (fetch-lpt-exchanges.sh, snippets/data/) - surfaces live token data in documentation context rather than directing users to a separate exchange site.
  • [Automations] Release tracking automation (update-livepeer-release.yml) keeps the current protocol version globally current. Any page referencing the current Livepeer version is automatically kept in sync with the actual release - preventing the stale version references that characterised v1.
  • [Automations] Forum integration (update-forum-data.yml) surfaces live community discussions alongside documentation. Users reading about a topic can see recent related forum posts without navigating away. This is the clearest implementation of documentation-as-ecosystem-surface.
  • [Content] Studio dashboard references systematically reviewed and reduced. Where Studio dashboard references remain, they are contextualised: “if you are using Studio as your gateway, see the Studio dashboard at livepeer.studio/dashboard” rather than presented as the primary action for all users.
  • [Technical] docs.json navigation configured with explicit external links to key ecosystem surfaces (Explorer, Studio, Governance portal, Discord) in the navigation sidebar - making the ecosystem connections visible at the navigation level, not just buried in page content.
  • [Product Positioning] About section documents the full Livepeer ecosystem - protocol, network, products, and community - giving users the mental model to understand how docs.livepeer.org relates to livepeer.studio, explorer.livepeer.org, and the governance portal. Context is set at the orientation layer, not retrofitted into each individual page.
Full verified integration with the governance portal has not been audited as a discrete deliverable. The governance portal is linked from the LP Token section, but whether the bidirectional connection (docs linked from governance portal) has been established is not confirmed. This is listed as an open item in the close-out task list.Analytics tracking at anchor level - which would surface which integration links users are actually clicking - has not been implemented. Without this signal, the quality of site integration can only be assessed structurally, not behaviourally. This is a gap in the feedback loop rather than the integration itself.An important nuance on the “duplication” constraint: in several cases where content appears duplicated across user-facing sections - for example, a gateway API reference card appearing in both the Developers section and the Gateways section - the underlying MDX content is served from a single canonical snippet file in snippets/components/ or snippets/data/. Both pages import from the same source. This means what appears as UI duplication is in fact single-source in the codebase: update the snippet once, and both surfaces reflect the change. This is a deliberate architecture decision that preserves user journey completeness (each persona sees the content they need in their section) without the maintenance burden of truly duplicated content. The source-of-truth-policy.md documents this pattern explicitly.
Last modified on March 12, 2026