# Exam question template — step-by-step guide

This is the exact format the exam creation form expects when you upload a
questions-and-answers file, instead of adding rows one at a time in the
browser.

## 1. Download the template

On the **Exams** page, click **Download the template (.csv)** above the
file upload field, or grab it directly from the repo at
`templates/exam-questions-template.csv`. It already contains a header row
and a few worked examples — open it and you'll see exactly what a valid
file looks like before you change anything.

## 2. The three columns, exactly as required

| Column | Required? | Accepted values |
|---|---|---|
| `question_text` | Always | Any text — the question itself. |
| `type` | Always | Exactly one of: `mcq`, `true_false`, `short_answer` (lowercase, no spaces). |
| `answer` | Required for `mcq` and `true_false`; leave blank for `short_answer` | The exact correct answer. |

**How grading uses `answer`:** for `mcq` and `true_false`, a student's
submitted answer is compared to this column as plain text, ignoring case
and leading/trailing spaces — so `Paris`, `paris`, and ` Paris ` all count
as correct if the answer column says `Paris`, but `Paris, France` would
not match. For `true_false`, use the literal words `true` or `false` in
the answer column. `short_answer` rows are never auto-scored — leave
`answer` blank; the host reviews these manually on the results page.

The template intentionally has **only these three columns**. Extra
columns (e.g. for multiple-choice options like A/B/C/D) aren't read by
the system yet — for now, write the correct option's full text directly
into `answer`, and put the options themselves inside `question_text` if
you want students to see them (e.g. *"Which is the capital of France? A)
London B) Paris C) Rome — type your answer"*).

## 3. Filling it in

You can edit the template in any of these:

- **Excel or Google Sheets** — open the `.csv` file directly, edit like a
  normal spreadsheet, and when saving, choose **CSV (Comma delimited)** or
  **CSV UTF-8** as the file type (not `.xlsx` — the system only reads
  `.csv`). Excel sometimes offers plain "CSV" and "CSV UTF-8 (Comma
  delimited)" — either works, but UTF-8 is safer if any question text
  uses non-English characters.
- **Notepad / any plain text editor** — write each question as one line,
  values separated by commas, matching the header order exactly:
  ```
  question_text,type,answer
  What is 7 x 8?,mcq,56
  Water is a compound.,true_false,true
  Describe Newton's second law.,short_answer,
  ```

**If a question or answer itself contains a comma**, wrap that whole
field in double quotes so it isn't mistaken for a column break:
```
question_text,type,answer
"Which of these are prime numbers: 2, 3, 4?",short_answer,
```

**Keep the header row** (`question_text,type,answer`) as the very first
line — don't delete or rename it, and don't reorder the columns.

## 4. Uploading it back

On the exam creation form, click **Browse** under "Questions and answer
key" and select your saved `.csv` file. **You do not also need to fill in
the manual question rows below it** — if a file is uploaded, it's used
as the complete question set and any rows added by hand in the form are
ignored entirely. (If you'd rather build the exam entirely by hand
instead, just skip the file and use the "Add question" rows as before.)

## 5. What happens if the file has a mistake

The system checks the file **on the server**, not just for a valid CSV
shape, and will reject it with a specific message rather than silently
dropping bad rows — for example:

- Missing or misnamed header → *"Template file must have columns named
  exactly: question_text, type, answer."*
- A `type` value that isn't one of the three allowed → *"Row 4: type must
  be exactly one of mcq, true_false, short_answer — got 'multiple'."*
- An `mcq`/`true_false` row with no answer → *"Row 2: answer is required
  for type 'mcq' (only short_answer can be left blank)."*

If you see one of these, fix that specific row in your spreadsheet, save,
and re-upload — the rest of the file doesn't need to be touched.

## 6. Worked example, start to finish

```
question_text,type,answer
What is the capital of Japan?,mcq,Tokyo
The Great Wall of China is visible from space with the naked eye.,true_false,false
Summarize the causes of the French Revolution.,short_answer,
```

Uploading this creates a 3-question exam: the first two are auto-scored
the moment a student submits, and the third appears in the host's results
view for manual reading — none of that requires any extra setup beyond
this one file.