# Design a good exam

Before producing JSON, design an assessment that gives the teacher useful evidence of what students know and can do. A valid document is not enough: every question should serve a clear learning goal.

## Start with the brief

Identify the subject, age or grade, language, topic, learning goals, time available, and any requested question types or accommodations. If a missing detail would materially change the assessment, ask one concise clarification; otherwise use a modest, age-appropriate scope and make no claims about a specific curriculum.

Do not present invented source material as teacher-provided, claim a curriculum alignment that was not requested, or include answer keys, marks, or student information in the printable document.

## Make a small assessment blueprint

Before writing questions, map the exam to a few objectives. Cover the important objectives in proportion to their importance, rather than creating several versions of the same question.

- Include recall only when it is needed; also test understanding, application, or reasoning when appropriate to the brief.
- Start with accessible questions, then progress to more demanding ones.
- Keep the total number and length of questions realistic for the available time.
- Avoid testing irrelevant reading load, memory, or trick interpretation when those are not the intended skill.
- Use independent questions whenever possible: an error in one answer should not make later questions impossible.

For a short check, three to five focused questions may be enough. For a longer verification, use a balanced mix of objectives and formats instead of many near-duplicate items.

## Choose a format that matches the evidence

Use the Printexam blocks to collect the kind of evidence the objective requires.

| Goal                                         | Suitable format                                                         |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| Recognise a fact, rule, or example           | `multiple-choice` with plausible alternatives                           |
| Recall a precise word, value, or short step  | `fill-text`                                                             |
| Explain, justify, compare, or show a method  | `text` prompt plus `open-response`                                      |
| Solve or interpret a mathematical expression | `math` with a `text` prompt and, when work is expected, `open-response` |

Multiple-choice alternatives must have one clearly best answer. Keep alternatives parallel in grammar and length, avoid clues such as “all of the above,” and do not use negative wording unless it is essential and prominent. Distractors should reflect realistic misconceptions, not obviously absurd answers.

For fill-in-the-blank questions, use a sentence that gives enough context and test one meaningful idea at a time. A word bank can reduce recall demand; include it only when that support matches the goal.

For open responses, state what students must do and provide enough lines for the expected answer. Do not ask for a paragraph in two lines or leave a one-word response with a large empty area.

## Write clear, fair questions

- Put the task in the question itself: say whether to identify, calculate, explain, compare, justify, or show work.
- Use vocabulary and sentence length suited to the requested students.
- Include all facts, data, units, and context needed to answer. Do not rely on unstated classroom knowledge.
- Use neutral, inclusive examples and avoid personal or sensitive data.
- Keep instructions concise and consistent. If an answer must include units, reasoning, or examples, say so.
- Preserve the user’s requested wording and language.

## Review before rendering

Check the completed assessment as both a teacher and a student.

1. Every question maps to an intended learning goal and the whole set covers the requested topic.
2. Each question has a clear answer or a clear expected kind of response, even though the printable JSON must not contain an answer key or scoring metadata.
3. The level, wording, and workload are appropriate for the requested students and time.
4. Questions do not accidentally reveal one another’s answers or depend on an earlier response.
5. The selected block gives students adequate space and makes the expected response clear.
6. The final document still follows the JSON schema and rendering rules.

Then follow the creation workflow in [`/create.md`](/create.md) to build, validate, and render the document.