Skip to content
Classroom

Question Writing Guide

Which engine build this documents

Everything in this section is verified against the vl-prod branch of the question engine. Upstream master carries a handful of extra macros that are not on this platform's build — where one is mentioned here it is marked. A live install can also carry local patches beyond its branch, so treat an unexpected "not a macro" error as worth reporting rather than worth working around.

Learn to create interactive, randomized questions for Varsity Learning assessments.

Getting Started

If you're new to question writing, start here:

  1. Question Parts — Understand the structure of a Varsity Learning question (setup code, question text, answer parts, hints, solutions)
  2. Basic Control Syntax — Define variables, do arithmetic, use conditionals
  3. Randomizers — Make values differ for each student

Core Concepts

Variables

All questions use variable definitions with a $ prefix:

$a = 5;                   // Number
$values = array(2,4,6);   // Array
$text = "example";        // String

Code Sections

The question editor has three boxes:

  • Common Control — all code: randomization, variables, $answer and every option variable
  • Question Text — the question as displayed (HTML and AsciiMath)
  • Detailed Solution — the worked solution

The answer type is chosen in the type selector, not written in code. Older questions may carry legacy qcontrol and answer code, which the editor appends to Common Control. See Question Types.

Math Display

Use backticks with AsciiMath notation:

The solution to `$a x = $b` is `x = $b/$a`

Features

Randomization & Variation

  • Randomizers — Create parametric questions where values change for each student

Visualizations

Mathematical Tools

  • Math Entry — Configure how students enter mathematical expressions

Answer Types

  • Question Types — How answer types work, with reference pages for 17 of them
  • Macros Reference — Built-in functions for formatting, math, strings, arrays

Reference

Control & Functions

Question Types

Numeric Response - Number — Integer or decimal inputs - Calculated — Numeric answers typed as arithmetic, such as 3/4 or sqrt(2) (no variables) - Complex Numbers — Complex number answers - N-Tuple — Ordered pairs, triples, etc. - Matrices — Matrix entries

Selection - Multiple Choice - Multiple Answer - Matching

Expressions - Function — Typed algebraic expression (for a student-drawn graph, use Drawing) - Intervals — Interval notation answers - Chemistry — Chemical formula and equation answers

Other - String — Short text responses - Essay — Free-response (manual grading) - Drawing — Student-drawn curves and constructions - File Upload — Student-submitted files - Multipart — Multiple sub-questions in one item - Conditional — Custom grading logic

Tips

Best Practices

  • Test your questions thoroughly before assigning them
  • Use meaningful variable names (e.g., $principal not $p)
  • Add hints to help students without giving away the answer
  • Use randomizers to discourage copying
  • Preview the question to see what students will see
  • Check that your question works correctly at the boundary values of your random range

Common Questions

Getting Help