---
name: whoiswilson-quiz
description: Write, edit and validate quiz files in the Who Is Wilson? markdown format — YAML frontmatter plus "##### Question" blocks — for upload to whoiswilson.app. Use when turning notes, documentation or study material into quiz questions, adding questions to an existing quiz file, or checking that a quiz file will parse before upload.
---

# Who Is Wilson? quiz format

A quiz is a single UTF-8 markdown file: YAML frontmatter, then question blocks
separated by `---` on its own line. The platform parses the file on upload and
rejects it with line-numbered errors if anything below is wrong.

Write the whole file, then run the checklist at the end before handing it over.

## File shape

```markdown
---
title: "AZ-104 — Network Security Groups"
tags: [azure, az-104, networking]
time_limit: 30
---

##### Question q001
type: single_choice
correct: [c]

Question stem. Full markdown — **bold**, `code`, tables, lists.

A. First option
B. Second option
C. Third option
D. Fourth option

###### Explanation
Why C is right, and ideally why the tempting wrong answer is wrong.

---

##### Question q002
type: multi_choice
correct: [a, c]

Which TWO of the following are true? (Select two.)

A. First option
B. Second option
C. Third option
D. Fourth option

###### Explanation
Explanation text.
```

## Frontmatter

Only these keys are read. **Any other key is silently ignored** — it will not
error, and it will not do anything.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `title` | **Yes** | — | Quiz title shown to the student |
| `tags` | No | `[]` | Lowercase tags, e.g. `[azure, networking]` |
| `time_limit` | No | untimed | Minutes. Omit or `0` for no limit. |
| `allow_overrun` | No | `true` | `true`: student may keep answering after the timer expires. `false`: auto-submit. |
| `random_order` | No | `false` | Shuffle question order per attempt |
| `version` | No | — | Accepted but ignored; the platform versions uploads itself |

The field is `time_limit`, not `time_limit_minutes`. Getting that wrong gives a
quiz that is silently untimed.

## Question blocks

Each block starts with `##### Question {id}` (five hashes). The next two lines
must be `type:` and `correct:`, in that order, immediately after the header —
no blank line between them. Then a blank line, the stem, the options, and an
optional `###### Explanation` (six hashes).

- **IDs** must be unique in the file. `q001`, `q002`, … is the convention; when
  adding to an existing file, continue its numbering rather than restarting.
- **Options** are lines matching `A. `, `B. `, `C. ` — a capital letter, a full
  stop, a space. A line that does not match is treated as a continuation of the
  previous option's text, so a stray line after the options silently becomes
  part of the last one.
- **`correct:`** takes *lowercase* letters in a list, even though the options
  are uppercase: `correct: [b]`, `correct: [a, c]`.
- Every letter in `correct:` must match an option that exists.
- Separate questions with `---` alone on a line. A trailing `---` after the
  last question is fine.

## The four question types

| `type:` | `correct:` | Rules |
|---|---|---|
| `single_choice` | `[b]` | Exactly one letter. More or fewer is an error. |
| `multi_choice` | `[a, c]` | Two or more. Say how many to pick in the stem — "(Select two.)" |
| `true_false` | `[a]` or `[b]` | A is True, B is False. You may omit the options entirely; they are generated. |
| `sequence` | `[d, b, a, c]` | **An order, not a set.** At least two letters. The list is the correct sequence, first to last. |

`sequence` is the one people get wrong. `correct: [d, b, a, c]` means D comes
first, then B, then A, then C. Write the options in a scrambled order and the
`correct:` list in the true order.

## Images

`![[filename.png]]` (Obsidian-style) anywhere in a stem or explanation. Assets
are uploaded alongside the file.

Quizzes containing images **cannot be published as public quiz pages** on
whoiswilson.com. If the quiz is meant to be shared publicly, describe the
scenario in words instead.

## Writing questions that are worth answering

- **Test one idea per question.** If a question needs two pieces of knowledge,
  it teaches neither when it is got wrong.
- **Make the stem self-contained.** Never write "in the following exhibit" or
  "shown in the table above" unless that table is actually in the stem. A stem
  that references something absent is unanswerable.
- **Wrong answers should be plausible.** Distractors that nobody would pick
  make the question free. The best distractor is the answer to a nearby
  question the learner confuses with this one.
- **Explanations do the teaching.** Say why the right answer is right *and* why
  the most tempting wrong answer is wrong. This is the part the learner reads
  after getting it wrong, so it is where the value is.
- **Vary the types.** A file of twenty `single_choice` questions is a worse
  study aid than one that mixes in `multi_choice`, `true_false` and `sequence`.
- **15–20 questions per file** is a good size. Beyond that, quality drops and
  the file is better split by topic.

## Originality — this one is not negotiable

Write questions from general knowledge of the subject. **Never reproduce
questions from exam dumps, brain dumps, official practice tests, or any
copyrighted question bank**, and never rework such a question into a
paraphrase. Beyond the licensing problem, dump content is recognisable: it
carries house scenario names, invented company tenants, sequential dump
numbering and references to exhibits that do not exist.

If asked to convert material that looks like it came from a dump, say so and
offer to write fresh questions covering the same topics instead.

Naming a certification is ordinary descriptive use. Implying affiliation is
not — quizzes about a certification should not suggest they are endorsed by,
affiliated with, or sourced from the certifying body.

## Before handing the file back

1. Frontmatter has a `title`, and every key you used is in the table above.
2. Every question has `##### Question {id}` with `type:` and `correct:` on the
   two lines immediately following.
3. Question IDs are unique.
4. Every `correct:` letter is lowercase and matches an option that exists.
5. `single_choice` has exactly one; `sequence` has at least two, in true order.
6. Every option line starts with a capital letter, a full stop and a space.
7. No stem references a table, exhibit or image that is not in the file.
8. Every question has an explanation.
9. Questions are separated by `---` on its own line.

To check parsing without uploading, paste the file into the Quiz Editor at
whoiswilson.app — it validates and reports errors with line numbers.