spoopyghosty0--frameport/docs/STYLE.md

Writing style for FramePort

Short rules so every screen, help text, doc and web page sounds the same. Code style is enforced by ruff.

Words

• Steam Frame on first mention in a screen or document, the Frame after that. Headset only for the physical device you wear ("put the headset on"). Buttons say "… on Frame" ("Install on Frame").
• Quest game for Meta Quest apps, Android app for ordinary Android apps, Linux app for Linux programs, PC VR game for Windows VR games (never "PCVR"). Say Oculus or Rift only for games that use Oculus's own SDK. Game when the kind doesn't matter; APK only when the file itself matters.
• Patch for anything in a game's patch list (never "fix" for the same thing). Recipe for a game's chosen patches and settings (never "config"); say what it is the first time a page uses it.
• Tools by their names: OVRPort, Revive, Proton, Lepton, SteamVR.
• Install (first time), Update (a newer build), Reinstall (the same build again); Play starts a game.
• Set up = the one-time setup of a Frame; connect = linking FramePort to it. Pair only in Valve's own Pair new host. The setup line is the fixed curl -fsSL https://frameport.app/s | bash; the setup command is the one with this PC's address and a one-time code. FramePort's button is Allow.
• Konsole is the Frame's terminal. The way there is "SteamVR dashboard → Launch a program → Desktop, then app menu → System → Konsole": say it in full once per page, then just "Konsole".
• This PC / your PC, not "computer". Unpack a download (zip and tar.gz alike), not "unzip".
• One label per thing everywhere: Docs, Report a problem, Download FramePort.

Form

• Buttons and headings in sentence case ("Add games", "Report a problem…"); one label per action everywhere.
• "…" at the end of a label when the action asks for more input (a dialog, a file picker).
• Sentences end with a period, including tooltips and help texts; labels and headings don't (also on the website).
• "and", not "&", in text. An em dash (—) for asides, a middle dot (·) between short facts.
• No Oxford comma ("Windows, macOS and Linux"). Straight apostrophes and quotes in source.
• Sizes in GiB/MiB (i18n.fmt_size), dates as YYYY-MM-DD HH:MM (i18n.fmt_datetime).
• US spelling (customize, analyze, color, license).
• Plain, technical wording: say what happens ("Steam restarts once"), no marketing adjectives.

Length

Short beats complete: say what the user does or gets; leave out how it works unless they need it to act.

• Buttons: four words at most. Tooltips: one short sentence.
• Dialog text: two short sentences. Help texts: three sentences at most (about 200 characters).
• Doc paragraphs: three sentences at most; steps as numbered lists.
• Explain a technical term in a few words where a reader first meets it, or leave it out.
• Say a thing once and link to it elsewhere.

Translations

• Every text the GUI shows goes through tr("…") or tr_n("…", "…", n) (see src/frameport/i18n.py); use templates with .format(), never f-strings inside tr(), and never decide anything from a displayed text.
• After changing texts run python scripts/i18n_extract.py (a test checks the template is current).
• CLI output, logs, diagnostics, catalog notes and launch-test diagnoses stay English.