[Docs] Write and link end-user documentation for GMs and players #390
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 onlyAPI.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.mdhas "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
Login.jsxlinks 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.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.mdlists every registered bot command from the same source of truth the/helptest uses.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,/helpand/record start's session picker.They live in the app, as markdown under
webapp/frontend/src/help/, imported with Vite's?rawand rendered by a smallHelpPageat/help/gmand/help/player. Three reasons overdocs/: 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.mdalready 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 matcheshelp.COMMANDS, the same source of truth/helpis built from.INTEGRATIONS.mdand the README both point at the in-app guides.One honest caveat in the GM guide: an instance that sets the registration-gate
INVITE_CODEwill 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.