Reference

Docs Site Standards

Use this reference to keep HotRoute docs pages consistent, coach-readable, linked to the right next steps, and supported by useful screenshots.

LiveDocs writers, support operators, product reviewers, and HotRoute staff who maintain or review user-facing docs.Updated June 7, 2026

Overview / Purpose

HotRoute docs should help a football coach understand what a page is for, when to use it, where to click, and what a good end state looks like.

This reference is the standard for route docs, screenshots, navigation, related links, in-app help links, and docs validation. It keeps the docs site predictable for users and easy for future docs agents to review.

Use this page before creating a new docs page, refreshing screenshots, adding a navigation item, or validating whether a product route has the right help link.

Who this is for

This page is mainly for people maintaining the docs site.

That includes docs agents, product reviewers, support operators, and staff members who need user-facing docs to match the product. It is also useful for reviewers who want to confirm whether a doc is written for coaches instead of engineers.

What to know first

The docs site is public and user-facing. Do not expose internal issue details, secrets, customer data, raw environment names, private emails, API keys, or repository-only implementation notes.

Current behavior must be separated from planned behavior. If a page describes something that is not fully live, mark the page with the correct status and state the boundary plainly.

Screenshots and examples should use meaningful demo data. Varsity Alpha, Week 1, and North Valley are the preferred demo story when they fit the route. Treat that data as illustrative, not customer proof.

Claims should stay disciplined. Use plain readiness language such as live, pilot, preview, planned, or illustrative when a doc could otherwise make a feature sound more available or proven than it is.

How it works

HotRoute docs are organized around the reader's job, not the codebase.

  • Start Here explains the product and the recommended first reading path.
  • Product Areas explains the five-area operating model: Modeling and Simulation, Design and Optimization, Learning and Cognition, Operations and Orchestration, and Collaboration and Memory.
  • Feature Guides explains the main product routes and route families a coach or operator will click through.
  • Workflows and Tutorials connects multiple product areas into practical work.
  • Coaching Philosophy / Operating Model explains how to think about HotRoute as a football operating system.
  • Administration covers owner, organization, access, billing, standards, and authority setup.
  • Reference covers glossary, FAQ, search, API, agent integration, and docs standards material.

Every public docs page lives under apps/docs/app/**/page.md. The navigation source of truth is apps/docs/lib/navigation-data.json.

Standard page format

Use this body structure for route-level feature and administration docs unless the page type clearly needs a variant:

  1. Overview / Purpose: what the page helps the reader understand or do.
  2. Who this is for: the football roles or review context.
  3. What to know first: access needs, setup assumptions, definitions, or product state.
  4. How it works: the concept or workflow in coach-readable language.
  5. Step-by-step instructions: exact click paths for product actions.
  6. What good looks like: the healthy end state.
  7. Common questions or mistakes: likely points of confusion.
  8. Related docs / next steps: the next useful pages.

Concept pages can replace the click path with sections such as Why this matters, How to think about it in football terms, and What this is not.

Reference pages can use grouped entries instead of a linear workflow, but they still need an Overview / Purpose and Related docs / next steps section when practical.

First-pass coverage map

The current first-pass docs plan covers these route families and sections.

Start Here and account setup:

Administration:

Team, people, and operations setup:

Playbook, design, and weekly preparation:

Intelligence, search, API, and agent support:

Every docs page should give the reader a useful next move.

Use related links in three ways:

  • Parent links point back to the broader product area or route family.
  • Child links point to a more specific setup or task page.
  • Companion links point to the next workflow a coach would naturally need.

Inline links should appear the first time a related concept is useful. The Related docs / next steps section should repeat only the most practical next pages.

Avoid dead ends. A route doc should not strand a reader after explaining only one screen.

Screenshot and demo data standard

Use Playwright for product screenshots. Do not fabricate product screens, manually mock UI, or crop out context needed for orientation.

Store screenshots under:

apps/docs/public/docs/<route-slug>/

Use ordered, action-readable filenames:

01-open-play-designer.png
02-click-new-play.png
03-review-published-play.png

Reference screenshots with the Markdoc figure tag. Use this shape, with the real route slug and filename:

figure
  src: /docs/play-designer/01-open-play-designer.png
  alt: Play Designer navigation item selected with the workspace open.
  caption: Open Play Designer from the left navigation.

Before capturing screenshots:

  • seed or reuse football-sensible demo data when the route would otherwise look empty
  • prefer the Varsity Alpha Week 1 North Valley story when it fits the route
  • keep seeded demo data available after capture when manual validation will reuse it
  • use a consistent desktop viewport, normally 1440x900
  • add mobile screenshots only when the mobile layout changes the instruction
  • hide secrets, invite links, private emails, real customer names, browser developer tools, and internal URLs
  • show enough surrounding UI for a coach to know where they are
  • use alt text that explains the screenshot for readers who cannot see it
  • keep captions short and action-oriented

Screenshots should be refreshed when the route layout changes, when demo data changes, when a screenshot becomes misleading, or when a claim label changes.

Product help buttons should point to the most specific docs page available. Avoid sending a user to the docs root when a route-level guide exists.

Use this target map when retargeting product help links:

Known follow-up pattern: if a product route currently builds a help URL from only NEXT_PUBLIC_DOCS_URL, retarget it to the matching page above during the next product UI pass for that route.

Manual validation and mismatch follow-ups

Manual validation should confirm both the product behavior and the docs that explain it.

When a validator finds a mismatch, create a focused follow-up instead of hiding the mismatch in the doc. The follow-up should include:

  • the product route
  • the docs page that describes it
  • the exact section or screenshot that is stale
  • what the product actually shows
  • what the doc expected the user to see
  • whether the fix belongs in product UI, docs content, screenshot data, or navigation/help links
  • the manual validation step that caught the mismatch

Use this rule for missing controls, renamed buttons, empty-state screenshots, outdated role names, incorrect access behavior, broken related links, and docs pages that describe a planned behavior as live.

What good looks like

A strong HotRoute docs page lets a coach answer:

  • What is this page for?
  • Who on the staff should use it?
  • What do I need before I start?
  • Where do I click?
  • What should I see after each important step?
  • What does a healthy end state look like?
  • What should I read or do next?

A strong docs set also has consistent navigation, live related links, current screenshots, football-sensible demo data, and route-level product help links that land on the right guide.

Current standards still to add

The docs standard is strong enough for first-pass route coverage. These standards should still be added as the docs program matures:

  • a named screenshot owner and refresh cadence
  • a reusable screenshot seed ledger for demo data and capture dates
  • a redaction checklist for screenshots and examples
  • a mobile screenshot rule that says when mobile capture is required
  • a shared helper for product help URLs so route-level docs links do not drift
  • a review path for planned, preview, and beta docs before they become live
  • a glossary expansion policy for football terms, product terms, AI terms, and operations terms

Read Getting Started to see the user-facing first reading path.

Read Glossary when a term needs to stay consistent across docs pages.

Read Home Dashboard and Navigation for a route-level guide with practical click instructions.

Read Organization Configuration for a mature administration guide that links parent, child, and companion docs.

Use FAQ / Help / Next Steps when a reader needs support direction after the docs path.

Read next

Getting StartedStart with the recommended reading path for new HotRoute users.GlossaryKeep docs language aligned with shared product and football terms.FAQ / Help / Next StepsUse common questions and support paths when a reader is blocked.Home Dashboard and NavigationSee the standard for route-level click instructions and screenshots.Organization ConfigurationReview a mature administration guide with parent, child, and companion links.
Previous
FAQ / Help / Next Steps
Next
Retrieval and Search