VGSpartansDocs

Type to search every page. Results are ordered by how well they match, then by where they sit in the contents, and only the letters you typed are highlighted.

The VGSpartans Handbook

Everything about how VGSpartans works, written down in one place, for students, admins and developers alike.

ExplanationFor everyone, admins, developers

VGSpartans is the campus web platform for Vista Grande High School. It is a handful of separate sites that share one account: club websites, personal pages, a wiki, a writing space, a discussion board, a newsroom, and the consoles that run all of it. This handbook covers every one of them, plus the machinery underneath.

Who this is for

There are three kinds of reader here, and most pages say at the top which ones they are written for.

  • Everyone. You have a school account and you want to use the platform. You never need to know what a Worker is.
  • Admins. You moderate content, manage people, or run a club console. You need to know exactly which button does what, and what happens after you press it.
  • On-call and developers. You keep it running, or you change it. You need the architecture, the runbooks, and the reasons behind the design.

Where to start

  • New to the platform? Start with Part 1, Getting started. It has one walkthrough per kind of reader.
  • Something is broken right now? Go straight to Part 6, Operations, and open the incident index. It is a table of symptoms: find yours, follow the runbook.
  • Want to know how a specific platform works? Part 2, Platform guides, has a chapter for each one.
  • Want to change the code? Part 7, Contributing, and Part 5, Architecture.

What this handbook promises

Two things, and they are the reason it is worth trusting during a bad day.

  1. Nothing here is guessed. Every claim about how the platform behaves was checked against the code that implements it, and the pages name the files. Where something could not be verified, the page says so instead of inventing an answer.
  2. A page that is not written says it is not written. Unfinished pages carry a notice and a pointer to whatever the real source of truth is today. None of them are padded out to look complete.

How to use this handbook explains the page types, the badges, and the conventions in more detail.

Where it lives

The handbook is markdown files in the platform’s own repository, under docs/handbook. The site you are reading renders them, and every page has an “Edit this page on GitHub” link at the bottom that opens the exact file. Fixing a wrong sentence is a pull request, the same as fixing a bug.

That placement is the point. Documentation kept somewhere else drifts from the code within a month. Documentation kept beside the code gets reviewed in the same pull request as the change it describes.

Download the whole handbook (PDF) Regenerated on every release. Useful offline, and on the day this site is the thing that is broken.

The nine parts

Part 0WelcomeWhat this handbook is, how it is organised, and how to read it.3 pagesPart 1Getting startedThree first-day walkthroughs: one for students, one for admins, one for developers.15 pagesPart 2Platform guidesOne chapter per platform: what it is, how to use it, who can do what, and what breaks.53 pagesPart 3AdministrationThe role model, the consoles, moderation, and the settings that govern the school.13 pagesPart 4SecurityHow sign-in, sessions, devices, bots, privacy and content safety actually work.15 pagesPart 5ArchitectureHow a request travels, how the workers split, and why each big decision went the way it did.13 pagesPart 6OperationsDeploys, migrations, backups, monitoring, and a runbook for every symptom.23 pagesPart 7ContributingThe workflow, the standards, the tests, and how to write for this handbook.8 pagesPart 8ReferenceThe lists: variables, config keys, routes, schemas, codes, tokens and scripts.13 pages

What is not in here

Two things about VGSpartans are written down somewhere other than this handbook, because neither belongs to it.

  • What Spartans know about Vista Grande. Club histories, traditions, courses, and everything else the school writes about itself lives in VGWiki, where anyone with a school account can edit it.
  • The code. VGSpartans is open source under the GNU AGPL v3. Every claim in this handbook is checked against the repository, and every page links to its own source file.

If neither of those and none of this answers your question, open a support ticket and a person will read it.