About classyQuiz

Live classroom quizzes, made from a teacher's exercise sheet by the teacher's own AI assistant. What follows describes the site for the assistants that make quizzes with teachers: what the site is for, what the quizzes are for, how a quiz is written, and what making one with a teacher is like.

What this site is for

A teacher has an exercise sheet and wants fifteen minutes of practice on exactly that content, in a form the class enjoys. Ready-made quizzes rarely match the sheet, and building one by hand in a quiz tool takes longer than the teacher has. Here the teacher's AI assistant reads the material and writes the quiz as plain text. The teacher pastes the text into this site, or drops the .zip there, and the class plays it.

During a quiz there are up to three screens. The projector shows the question and the answers to the class. Each student answers on their own phone or tablet by tapping a colour. The teacher steers: next question, reveal, ranking, and fixing a question that turns out to be wrong.

How a lesson runs. The teacher pastes the quiz into the box on this page, or drops the file there, usually on the laptop connected to the projector. That screen then shows the quiz's five-digit code and a QR code, the students who joined, and the teacher's Start button; the questions are listed below it for a last check, with their answers folded away. Students open the site on their tablets and type the code, or scan the QR code. Started, the projector shows each question, and a slim bar on it carries the teacher's next step: reveal, next, ranking; a presentation clicker or the space bar does the same. A teacher who wants to steer from their phone opens the site's /teacher page on it, types the code and chooses Remote; the projector then shows only what the class should see. A laptop with a second screen can open the projector in a window of its own and keep the steering on the laptop. A teacher who pasted the quiz on the phone opens /teacher on the projector computer and chooses Projector. Both are set up before the students get the code: once students have joined, no other device can take over the steering, so a student can't either. If the phone's battery dies, the projector takes the steering back by itself.

Nobody has an account. Students join with a number or a QR code and appear as randomly assigned avatars, never by name. Nothing is public and nothing is kept beyond its use: a quiz can only be reached with its code, which the teacher gives the class. A quiz stays on the site only while it is in use: until the teacher ends it, or two days after it was last used. The teacher's lasting copy is the text or file the assistant produced. A run's answers and scores are deleted an hour after the run ends. A quiz is the teacher's own material, made from their sheets for their own class. That is the use the copyright exceptions for teaching allow, in Switzerland and many other countries, and it is why the site keeps a quiz within that class.

This site runs on a free hosting plan meant for a few teachers. Anyone can run their own copy for their school or for themselves: the code is public at github.com/sacrusha/ClassyQuiz, and setting it up on a free Cloudflare account takes five to ten minutes, with an AI assistant's help or by following the guide there.

An assistant reading this page has usually been given just the site's address, by a teacher who has material in hand and a lesson coming up. Assistants can't upload to the site. The teacher pastes what the assistant wrote, or drops its .zip on the site.

What the quizzes are for

Practice, not testing. The quiz is a short, lively way to go through the content the class is working on. Nobody is graded. The ranking shows avatars, so a low place exposes nobody, and it gives the class a moment of closure at the end.

A teaching moment. The teacher sets the tempo: a question stays up as long as the teacher wants, and the teacher reveals the answer when the class is ready. The reveal shows how many students picked each answer. That is where the wrong answers earn their place. When the wrong answers are the mistakes students actually make, the class sees that nine of them took 25 francs off the price instead of 25 percent, and the teacher can take it from there. Wrong answers that nobody would pick make a question trivial and teach nothing.

Read from the back of the room. The question and its answers are read on a projector, often by students who read slowly or don't read the language well, with the teacher there to read aloud. Short questions and short answers work best: an answer is a button, not a paragraph. A calculation that takes a minute or two in the head or on scrap paper fits. A long derivation doesn't.

Up to four answers; usually one of them is right. Each answer position has its own colour and shape on every screen. The site shuffles each question's answers when the quiz is uploaded, the same way on every screen, so the class can't learn where the right one sits; writing the right answer first might be convenient. Where the order carries meaning, a question keeps it (see Order: below).

About fifteen minutes. With pauses to explain, that is often ten to fifteen questions. What the teacher asks for overrides this.

Used once. A quiz is usually made shortly before the lesson, often in the break, and played once, perhaps again in a parallel class. The teacher's time is the scarce resource. A quiz that is good enough, on the right content and with correct keys, beats a polished one that arrives late.

Any language. This page is in English. Quizzes are in the language of the teacher and the material. The few keywords of the format (Title:, Image:, Background:, Order: fixed) stay in English whatever the quiz language, because the site recognises them.

How quizzes are built

A quiz is plain text. An example, made from a photographed sheet on percentages:

Title: Percentages

1. What is 10% of 250?
- 2.5
+ 25
- 250
- 10

2. A jacket costs 80 francs and is reduced by 25%. What does it cost now?
- 55 francs
- 20 francs
- 75 francs
+ 60 francs

3. Which is the most?
+ 50% of 40
- 30% of 50
- 10% of 120

The parts

• Title. The first line, Title: followed by the title. It is shown to the class at the start.
• Questions are numbered 1., 2., … The text may run over several lines. A question line never starts with + or - , because those mark answers.
• Answers follow their question, one per line, between two and four of them. The correct answer's line starts with + , each wrong answer's line with - . Usually exactly one answer is correct. A question may have more than one right answer, up to all of them; each is marked +, and a student who picks any one of them scores. The marker sits on the answer's own line so that a teacher glancing at the text sees the key next to the answer, and can move it by changing one character.
• Pictures. A question can show one picture: the figure, diagram, chart or drawing its exercise depends on. The line Image: q3.png after the question text, before the answers, names the picture's file. It belongs on the projector with the question; the students' devices show only the answer buttons.
• Answer order. The site shuffles each question's answers. A question whose answers have an order that carries meaning, such as "none of these" last, the steps of a sequence, or numbers rising, keeps the order as written with the line Order: fixed after the question text, before the answers. Before the first question, the line keeps the order of every question. Answers that are just letters in order, such as A, B, C naming parts of a figure, keep their order anyway.
• Backgrounds. A picture behind the question, for atmosphere or context rather than content, is a separate line: Background: forest.jpg. Before the first question it lies behind every question; after a question's text it lies behind that question only, in place of the quiz's. The question and its answers stay readable over it.

Pictures and backgrounds are files that travel with the quiz text in a .zip; pasted text can't carry them. The same file can serve several questions, as a picture or as a background. Names are matched without regard to folders or upper and lower case. PNG, JPEG, GIF, WebP and SVG can be read; HEIC photos from iPhones mostly can't. At upload, the teacher's browser scales every picture down to what a projector shows and drops everything it carries besides the image, such as a photo's location. A figure cropped out of a photographed sheet is what reads from the back of the room; the whole page would be too small, and anything else on it, such as a solution written in or a student's name, would be on the wall too.

Nothing else belongs to the quiz: no answer letters, explanations, solutions sections or messages to the teacher. The quiz is the finished piece the class sees; what the assistant has to tell the teacher belongs in the conversation, before the quiz is handed over. Text before the title or after the last question is treated as conversation and ignored. Text between questions that isn't a question, an answer or a picture line is reported as an error. The site shows text as written, without Markdown formatting. Mathematical notation is written in plain text with ordinary characters: x², ½, √2, 3 × 4, 12 ÷ 3, a ≤ b. A formula that plain text can't show, such as a fraction of fractions, can be the question's picture.

The projector's layout for a question, as HTML and CSS, is at classyquiz.pages.dev/layout.html.

Getting the quiz to the site

In a chat, the quiz arrives as one code block. Two quizzes, e.g. one for each of two classes, are two blocks, pasted one at a time. The chat then shows a copy button, and the + and - markers survive the copy. Outside a code block, chat apps turn those lines into bullet points and the key is lost. The site takes no single text file; a file is a .zip. A quiz with pictures is always one: the quiz text as one .txt or .md file, and the picture files beside it. An assistant that can run code can crop figures out of the photographed or scanned sheets for it. The teacher pastes the text, or drops the .zip, on this site's start page.

The site then shows the teacher the quiz's questions, with their right answers a tap away, so a wrong key can be spotted and fixed before the lesson. If something can't be read (a question without a marked answer, five answers, a stray bullet point), the site lists each problem with the question it belongs to, in words a teacher can paste straight back into the chat. Some things only get a warning: no title, the same answer twice, a very long answer. The quiz runs anyway. A picture the quiz names that isn't in the .zip, or that the browser can't open, is listed the same way, and the teacher can also choose to run the quiz without it.

Making a quiz with a teacher

Making a quiz is a conversation, not a delivery. The teacher knows which quiz they want; the assistant doesn't, until it finds out. What the teacher wants can arrive in any form:

• in the message;
• in a handwritten note photographed among the sheets;
• in the margins of the sheet itself: ticked exercises, crossed-out ones, "only 3 to 5";
• or not at all, until someone asks.

Three wishes come up again and again, often mixed in one quiz:

• Transfer. The sheet's exercises become questions one to one. The class meets in the quiz what it practised or is about to practise. An exercise that has no ready answer choices gets them from the mistakes students typically make. When the sheet has solutions they are a help, but not proof: sheets have typos, and a photo can blur a digit.
• Variants. The exercises are multiplied: same skill, new numbers or new words, so the class practises the method rather than remembering the sheet. A parallel class may get a different set of variants.
• Topic. The assistant takes the topic from the sheet and explores which questions work in quiz form. This is useful when the sheet's own exercises don't fit multiple choice, e.g. proofs, essays, drawings or experiments.

Much of what shapes a good quiz is something only the teacher knows:

• which exercises;
• how many questions;
• how hard, for this class;
• whether the class has already done the sheet (a review) or is about to (a preview);
• whether the sheet's own numbers or new ones.

Some of it is visible in the material, some of it in what the teacher wrote, and some of it in neither.

Time shapes the conversation. Often the teacher is in the ten-minute break before the lesson, perhaps on a phone. Every round of questions costs some of those minutes. A quiz that isn't what the teacher wanted costs more, and is discovered in front of the class. A teacher who sent a full brief has already answered everything. A pile of photos with contradictory markings may need a question or two. A question that offers a reading of the material is quick to answer, e.g. "I read the note as: exercises 2 to 6, as variants with new numbers." So is one that offers a choice. An open question is slower. Some teachers prepare the evening before and are glad of a longer exchange.

The material is usually photos taken with a phone: skewed, partly cut off, with handwriting in the margins. Sometimes it is a PDF or a document. When something can't be read with confidence, that matters most where it touches a key. The place to say so is the conversation, while the teacher is there to answer, and before the quiz is handed over: a reading the teacher can confirm is quickest, e.g. "4b is blurred; I read it as 3/8." Once the quiz is on the site, nothing from the assistant reaches the teacher; a key that turns out wrong in class is fixed there by the teacher.

The conversation often goes on after the quiz is delivered:

• the teacher asks for changes;
• pastes back a message from the site;
• reports a key that was wrong in class;
• or asks for a fresh set of variants for the next class.

The conversation itself is in the teacher's language. The quiz is in the language of the material, unless the teacher wants otherwise.