rbrooks/Quest-Board

Watch

Fork 0

[Docs] Write and link end-user documentation for GMs and players #390

New issue

Closed

opened 2026-08-25 20:42:26 +00:00 by claude-bot · 2 comments

claude-bot commented

2026-08-25 20:42:26 +00:00

Collaborator

Impact: MEDIUM

Found in the August 2026 session lifecycle review (#319).

What the user experiences

There is no end-user documentation of any kind. Every file in docs/ is written for whoever deploys or develops the stack. A player or GM with a "how do I…" question has no in-product or linked fallback to answer it — the only escape hatch is messaging the product owner directly. This gap starts at the very first screen: the login page's only copy is "Quest Board", "TTRPG session scheduling", and a button labelled "Sign in with SSO" — engineer vocabulary, no mention of recording, summaries, or the wiki, and no product explanation for someone who hasn't used it before.

Evidence

docs/ contains only API.md, DEVELOPMENT.md, INTEGRATIONS.md, OPERATIONS.md, ROADMAP-COMPLETED.md, security-remediation-plan.md, security-rollout-checklist.md — all developer- or operator-facing.
docs/INTEGRATIONS.md has "Discord Commands" and "Discord Account Linking" sections, but nothing in the app links to them, and they document only 6 of the 10 bot commands (missing /quests, /history, /link, /unlink).
webapp/frontend/src/pages/Login.jsx:25-40 — the only copy is the product name, a scheduling-only tagline, and a "Sign in with SSO" button; no signup path, no product explanation.

Why it matters for a hosted product

For a hosted product, the app itself has to teach, or a linked fallback has to — today neither exists. Every "how do I…" becomes a direct message to the owner, which does not scale past a handful of self-hosted groups.

Proposed fix

Write two pages: "Running your first campaign" (GM) and "Joining a campaign" (player), covering scheduling, Discord linking, recording, the wiki, and prep at a user level. Link them from the dashboard and from Login.jsx. Rewrite the Login page's tagline to name the product's actual scope (scheduling, recording, summaries, wiki) instead of "TTRPG session scheduling" alone, and replace or supplement "Sign in with SSO" with plainer language. This is the audit's M6 and §7.3, plus the Login-page finding from journey step 0.

Acceptance criteria

A GM-facing "Running your first campaign" guide exists and covers scheduling, Discord linking, recording, and prep.
A player-facing "Joining a campaign" guide exists and covers linking, voting/RSVP, and finding recaps.
Both guides are linked from the dashboard.
Login.jsx links to the new guides and no longer describes the product as scheduling-only.
docs/INTEGRATIONS.md's Discord Commands section lists all ten bot commands, not six.

**Impact: MEDIUM** Found in the August 2026 session lifecycle review (#319). ## What the user experiences There is no end-user documentation of any kind. Every file in `docs/` is written for whoever deploys or develops the stack. A player or GM with a "how do I…" question has no in-product or linked fallback to answer it — the only escape hatch is messaging the product owner directly. This gap starts at the very first screen: the login page's only copy is "Quest Board", "TTRPG session scheduling", and a button labelled "Sign in with SSO" — engineer vocabulary, no mention of recording, summaries, or the wiki, and no product explanation for someone who hasn't used it before. ## Evidence - `docs/` contains only `API.md`, `DEVELOPMENT.md`, `INTEGRATIONS.md`, `OPERATIONS.md`, `ROADMAP-COMPLETED.md`, `security-remediation-plan.md`, `security-rollout-checklist.md` — all developer- or operator-facing. - `docs/INTEGRATIONS.md` has "Discord Commands" and "Discord Account Linking" sections, but nothing in the app links to them, and they document only 6 of the 10 bot commands (missing `/quests`, `/history`, `/link`, `/unlink`). - `webapp/frontend/src/pages/Login.jsx:25-40` — the only copy is the product name, a scheduling-only tagline, and a "Sign in with SSO" button; no signup path, no product explanation. ## Why it matters for a hosted product For a hosted product, the app itself has to teach, or a linked fallback has to — today neither exists. Every "how do I…" becomes a direct message to the owner, which does not scale past a handful of self-hosted groups. ## Proposed fix Write two pages: "Running your first campaign" (GM) and "Joining a campaign" (player), covering scheduling, Discord linking, recording, the wiki, and prep at a user level. Link them from the dashboard and from `Login.jsx`. Rewrite the Login page's tagline to name the product's actual scope (scheduling, recording, summaries, wiki) instead of "TTRPG session scheduling" alone, and replace or supplement "Sign in with SSO" with plainer language. This is the audit's M6 and §7.3, plus the Login-page finding from journey step 0. ## Acceptance criteria - [ ] A GM-facing "Running your first campaign" guide exists and covers scheduling, Discord linking, recording, and prep. - [ ] A player-facing "Joining a campaign" guide exists and covers linking, voting/RSVP, and finding recaps. - [ ] Both guides are linked from the dashboard. - [ ] `Login.jsx` links to the new guides and no longer describes the product as scheduling-only. - [ ] `docs/INTEGRATIONS.md`'s Discord Commands section lists all ten bot commands, not six.

claude-bot added this to the v4.3.0 - Product Surface: Navigation, Attention & Feedback milestone

2026-08-25 20:42:26 +00:00

claude-bot added the

enhancement

frontend

labels

2026-08-25 20:42:26 +00:00

claude-bot referenced this issue

2026-09-06 00:34:01 +00:00

v4.3.0 build order: Product Surface in eight phases #514

claude-bot commented

2026-09-06 06:08:11 +00:00

Author

Collaborator

Picking this up as v4.3.0 phase 7 (#514), right after #387 on the same lane so the guides can describe the invite link. Decisions: the two guides ship inside the app as public help pages (/help/gm, /help/player) rendered from markdown bundled with the frontend, so they version with the product and a player can read "Joining a campaign" before they have an account; linked from the dashboard and the login page; the login tagline names the real scope and the button stops saying "SSO"; docs/INTEGRATIONS.md lists every registered bot command from the same source of truth the /help test uses.

Picking this up as v4.3.0 phase 7 (#514), right after #387 on the same lane so the guides can describe the invite link. Decisions: the two guides ship inside the app as public help pages (`/help/gm`, `/help/player`) rendered from markdown bundled with the frontend, so they version with the product and a player can read "Joining a campaign" before they have an account; linked from the dashboard and the login page; the login tagline names the real scope and the button stops saying "SSO"; `docs/INTEGRATIONS.md` lists every registered bot command from the same source of truth the `/help` test uses.

rbrooks referenced this issue from a commit

2026-09-06 07:06:32 +00:00

docs(webapp): guides for the people who use Quest Board, not just run it (#390)

claude-bot referenced this issue from a pull request that will close it,

2026-09-06 07:06:49 +00:00

feat(webapp): a shareable invite link, a first-run checklist, and guides for the people who use Quest Board (phase 7a of v4.3.0) #530

claude-bot commented

2026-09-06 07:07:04 +00:00

Author

Collaborator

Done in the phase 7a PR (auto-merging on green); ships with v4.3.0.

Two guides, "Running your first campaign" and "Joining a campaign", written for the reader rather than the maintainer, describing the app as it is on main: the nav bar, "Needs you", RSVP, the /join/<code> links from #387, the Prep lane and the shelf, the post-session checklist, /help and /record start's session picker.

They live in the app, as markdown under webapp/frontend/src/help/, imported with Vite's ?raw and rendered by a small HelpPage at /help/gm and /help/player. Three reasons over docs/: one click from where the question is asked, they version with the features they describe, and they ship in the bundle rather than being fetched. The routes are public on purpose: the reader who most needs "Joining a campaign" has not signed up yet, which is what lets the sign-in page and the invite page link to it and have the link work.

Linked from a quiet Help line under the dashboard's campaign list, from the invite page, and from Login.jsx, whose tagline now names the real scope instead of "TTRPG session scheduling" and whose button says "Sign in". No provider name next to it: there is no provider-name setting anywhere in config and no public endpoint to read one from, and adding both for a docs issue was the wrong trade.

One correction to the issue: docs/INTEGRATIONS.md already listed all eleven commands (a previous phase fixed that). So the work there was stopping it drifting again: the bot suite now parses the Discord Commands table and asserts it matches help.COMMANDS, the same source of truth /help is built from. INTEGRATIONS.md and the README both point at the in-app guides.

One honest caveat in the GM guide: an instance that sets the registration-gate INVITE_CODE will still refuse a brand-new player following a campaign invite link, because those are two different secrets and the login return path does not carry the second. Naming it seemed better than leaving it to be discovered. Tests: 7 for the help pages, 3 on the login page, 1 on the dashboard, 1 in the bot suite.

Done in the phase 7a PR (auto-merging on green); ships with v4.3.0. Two guides, "Running your first campaign" and "Joining a campaign", written for the reader rather than the maintainer, describing the app as it is on main: the nav bar, "Needs you", RSVP, the `/join/<code>` links from #387, the Prep lane and the shelf, the post-session checklist, `/help` and `/record start`'s session picker. They live in the app, as markdown under `webapp/frontend/src/help/`, imported with Vite's `?raw` and rendered by a small `HelpPage` at `/help/gm` and `/help/player`. Three reasons over `docs/`: one click from where the question is asked, they version with the features they describe, and they ship in the bundle rather than being fetched. The routes are public on purpose: the reader who most needs "Joining a campaign" has not signed up yet, which is what lets the sign-in page and the invite page link to it and have the link work. Linked from a quiet Help line under the dashboard's campaign list, from the invite page, and from `Login.jsx`, whose tagline now names the real scope instead of "TTRPG session scheduling" and whose button says "Sign in". No provider name next to it: there is no provider-name setting anywhere in config and no public endpoint to read one from, and adding both for a docs issue was the wrong trade. One correction to the issue: `docs/INTEGRATIONS.md` already listed all eleven commands (a previous phase fixed that). So the work there was stopping it drifting again: the bot suite now parses the Discord Commands table and asserts it matches `help.COMMANDS`, the same source of truth `/help` is built from. `INTEGRATIONS.md` and the README both point at the in-app guides. One honest caveat in the GM guide: an instance that sets the registration-gate `INVITE_CODE` will still refuse a brand-new player following a campaign invite link, because those are two different secrets and the login return path does not carry the second. Naming it seemed better than leaving it to be discovered. Tests: 7 for the help pages, 3 on the login page, 1 on the dashboard, 1 in the bot suite.

claude-bot closed this issue

2026-09-06 07:37:13 +00:00

claude-bot referenced this issue

2026-09-06 07:42:57 +00:00

v4.3.0 build order: Product Surface in eight phases #514

claude-bot referenced this issue

2026-09-06 09:30:26 +00:00

chore(release): v4.3.0 #533