About these docs

A short note for anyone writing or PRing docs.

Voice

• Second person. "You'll see…" not "The user will see…"
• Plainspoken. Skip jargon when a normal word works. "Sign in" not "authenticate". "School" not "organizational unit".
• Action-oriented. Lead with what the reader is trying to do. "Submit a ticket" beats "About the ticket submission flow".
• Honest about scope. If a feature has a quirk, say so. If something is in beta, label it.

Structure

• One article = one task. If the title can't be a verb phrase, the page is probably trying to do too much.
• Lead with the answer. First paragraph should resolve the why-am-I-here question. Save the architecture stuff for "How it works" sub-sections.
• Show, then explain. A code block, screenshot, or step list before paragraphs of prose.

Mechanics

• Use Material's admonitions (!!! note, !!! warning) sparingly. Reserve warning for "this might break things."
• For Q&A, use collapsible ??? question blocks so the page stays scannable.
• Link to source-of-truth pages (status, marketing, GitHub) using the canonical https://*.supportstudiok12.com or github.com/BardSec/supportstudiok12 URLs.
• Avoid screenshots until the UI is stable. Old screenshots age fast and erode trust.

What not to write

• Don't restate the marketing site. That's supportstudiok12.com's job. Help docs are for users who are already in (or about to be in) the product.
• Don't promise a roadmap here. That belongs on the marketing site or the changelog. Docs describe what exists today.
• Don't reference internal-only details. Anything about the operator console, internal scripts, or business logic that customers shouldn't need to know about.

Adding a page

1. Create the .md file under docs/ in the right section.
2. Add a frontmatter block with title: (used in the browser tab and search).
3. Add the page to nav: in mkdocs.yml. We only list pages that exist — no dead-link stubs.
4. Run mkdocs serve locally and skim the rendered page.
5. Push. Cloudflare Pages auto-deploys.