1: Introduction
- Page ID
- 488650
\( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)
\( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)
\( \newcommand{\dsum}{\displaystyle\sum\limits} \)
\( \newcommand{\dint}{\displaystyle\int\limits} \)
\( \newcommand{\dlim}{\displaystyle\lim\limits} \)
\( \newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\)
( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\)
\( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\)
\( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\)
\( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\)
\( \newcommand{\Span}{\mathrm{span}}\)
\( \newcommand{\id}{\mathrm{id}}\)
\( \newcommand{\Span}{\mathrm{span}}\)
\( \newcommand{\kernel}{\mathrm{null}\,}\)
\( \newcommand{\range}{\mathrm{range}\,}\)
\( \newcommand{\RealPart}{\mathrm{Re}}\)
\( \newcommand{\ImaginaryPart}{\mathrm{Im}}\)
\( \newcommand{\Argument}{\mathrm{Arg}}\)
\( \newcommand{\norm}[1]{\| #1 \|}\)
\( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\)
\( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\AA}{\unicode[.8,0]{x212B}}\)
\( \newcommand{\vectorA}[1]{\vec{#1}} % arrow\)
\( \newcommand{\vectorAt}[1]{\vec{\text{#1}}} % arrow\)
\( \newcommand{\vectorB}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)
\( \newcommand{\vectorC}[1]{\textbf{#1}} \)
\( \newcommand{\vectorD}[1]{\overrightarrow{#1}} \)
\( \newcommand{\vectorDt}[1]{\overrightarrow{\text{#1}}} \)
\( \newcommand{\vectE}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash{\mathbf {#1}}}} \)
\( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)
\(\newcommand{\longvect}{\overrightarrow}\)
\( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)
\(\newcommand{\avec}{\mathbf a}\) \(\newcommand{\bvec}{\mathbf b}\) \(\newcommand{\cvec}{\mathbf c}\) \(\newcommand{\dvec}{\mathbf d}\) \(\newcommand{\dtil}{\widetilde{\mathbf d}}\) \(\newcommand{\evec}{\mathbf e}\) \(\newcommand{\fvec}{\mathbf f}\) \(\newcommand{\nvec}{\mathbf n}\) \(\newcommand{\pvec}{\mathbf p}\) \(\newcommand{\qvec}{\mathbf q}\) \(\newcommand{\svec}{\mathbf s}\) \(\newcommand{\tvec}{\mathbf t}\) \(\newcommand{\uvec}{\mathbf u}\) \(\newcommand{\vvec}{\mathbf v}\) \(\newcommand{\wvec}{\mathbf w}\) \(\newcommand{\xvec}{\mathbf x}\) \(\newcommand{\yvec}{\mathbf y}\) \(\newcommand{\zvec}{\mathbf z}\) \(\newcommand{\rvec}{\mathbf r}\) \(\newcommand{\mvec}{\mathbf m}\) \(\newcommand{\zerovec}{\mathbf 0}\) \(\newcommand{\onevec}{\mathbf 1}\) \(\newcommand{\real}{\mathbb R}\) \(\newcommand{\twovec}[2]{\left[\begin{array}{r}#1 \\ #2 \end{array}\right]}\) \(\newcommand{\ctwovec}[2]{\left[\begin{array}{c}#1 \\ #2 \end{array}\right]}\) \(\newcommand{\threevec}[3]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \end{array}\right]}\) \(\newcommand{\cthreevec}[3]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \end{array}\right]}\) \(\newcommand{\fourvec}[4]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \\ #4 \end{array}\right]}\) \(\newcommand{\cfourvec}[4]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \\ #4 \end{array}\right]}\) \(\newcommand{\fivevec}[5]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \\ #4 \\ #5 \\ \end{array}\right]}\) \(\newcommand{\cfivevec}[5]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \\ #4 \\ #5 \\ \end{array}\right]}\) \(\newcommand{\mattwo}[4]{\left[\begin{array}{rr}#1 \amp #2 \\ #3 \amp #4 \\ \end{array}\right]}\) \(\newcommand{\laspan}[1]{\text{Span}\{#1\}}\) \(\newcommand{\bcal}{\cal B}\) \(\newcommand{\ccal}{\cal C}\) \(\newcommand{\scal}{\cal S}\) \(\newcommand{\wcal}{\cal W}\) \(\newcommand{\ecal}{\cal E}\) \(\newcommand{\coords}[2]{\left\{#1\right\}_{#2}}\) \(\newcommand{\gray}[1]{\color{gray}{#1}}\) \(\newcommand{\lgray}[1]{\color{lightgray}{#1}}\) \(\newcommand{\rank}{\operatorname{rank}}\) \(\newcommand{\row}{\text{Row}}\) \(\newcommand{\col}{\text{Col}}\) \(\renewcommand{\row}{\text{Row}}\) \(\newcommand{\nul}{\text{Nul}}\) \(\newcommand{\var}{\text{Var}}\) \(\newcommand{\corr}{\text{corr}}\) \(\newcommand{\len}[1]{\left|#1\right|}\) \(\newcommand{\bbar}{\overline{\bvec}}\) \(\newcommand{\bhat}{\widehat{\bvec}}\) \(\newcommand{\bperp}{\bvec^\perp}\) \(\newcommand{\xhat}{\widehat{\xvec}}\) \(\newcommand{\vhat}{\widehat{\vvec}}\) \(\newcommand{\uhat}{\widehat{\uvec}}\) \(\newcommand{\what}{\widehat{\wvec}}\) \(\newcommand{\Sighat}{\widehat{\Sigma}}\) \(\newcommand{\lt}{<}\) \(\newcommand{\gt}{>}\) \(\newcommand{\amp}{&}\) \(\definecolor{fillinmathshade}{gray}{0.9}\)There are plenty of guides for writing mathematics assessment questions in WeBWorK. This guide takes a different approach and is written for people in the sciences and other descriptive fields, especially in the life sciences.
This book assumes you want questions that read like real lab and lecture tasks, grade reliably, and are easy to reuse across semesters.
This book assumes you are a domain expert, not a software developer. The patterns shown here are designed so that you can reason about biology first and let the templates handle the mechanics.
This guide is based on the PG 2.17 subset used in ADAPT and webwork-pg-renderer, so some macros from full WeBWorK installs are not available. Use the macro allowlist reference in Sections within a PG question before you try to load new interaction macros.
On this page
| Section | What it covers |
|---|---|
| What this guide emphasizes | The PGML-first mindset, science-first tone, and subset constraints. |
| PG vs PGML (a practical split) | A concrete rule of thumb for what goes where. |
| Where to start today | A task-to-chapter map for quick entry. |
| Apply it today | Two actions you can take immediately. |
What this guide emphasizes
- PGML-first authoring: write the student-facing prompt in PGML and keep regular PG as short setup code for values and answer checking.
- Life-science style prompts: short narratives, concentrations and dilution workflows, structured data, and interpretation questions that match how biology is taught and practiced.
- Practical reuse: stable patterns you can clone and copy-edit to build question banks quickly without breaking grading.
- Subset-aware authoring: the ADAPT and webwork-pg-renderer PG 2.17 subset lacks some macros, so check the allowlist in Sections within a PG question before adding new interaction types.
PG vs PGML (a practical split)
| Layer | Use it for | Avoid using it for |
|---|---|---|
| PG (setup) | Macros, context, variables, answer checkers. | Long prompt text, hand-built formatting. |
| PGML (prompt) | Student-facing sentences, math, tables, blanks. | Hidden logic and heavy computation. |
Where to start today
This guide is organized as short pages you can read out of order. Pick the path that matches what you are doing today.
| If you are doing this today | Start here | What you get |
|---|---|---|
| Make one working problem fast | Quickstart: Edit Your First Problem | A safe copy-edit loop and a minimal working skeleton. |
| Set up a new file correctly | Problem Generation (PG) | Minimal scaffolding that stays readable. |
| Write or edit the prompt text | PGML (PG Markup Language) | PGML patterns for blanks, lists, tables. |
| Understand the anatomy of a full problem | Breaking Down the Components | OPL header plus four sections in one worked example. |
| Pick an interaction type | Different Question Types | A catalog of common question types. |
| Build biology-first patterns | Advanced PGML Techniques | Advanced PGML techniques for HTML, tables, and matching. |
| Fix a generic ADAPT error | Testing and Debugging | Local rendering with line-level error messages. |
If you want a quick vocabulary reset before you start, use Common terms and names for the common terms used throughout the book.
Apply it today
- Pick one page that matches what you are building today and copy-edit the example rather than starting from scratch.
- Keep regular PG minimal and write student-facing sentences in PGML.
- 1.1: What is WeBWorK?
- Explains what WeBWorK is by showing how a problem file defines randomized values, prompts, answer blanks, and grading rules using PG for setup and PGML for student-facing content. After finishing, you can separate minimal setup from the PGML prompt and understand that this guide targets a flattened PG macro tree. Use it when you need a clear mental model of what a WeBWorK problem file does, especially for biology prompts with concentrations, dilutions, or fold-change calculations.
- 1.2: Why use WeBWorK?
- Describes why WeBWorK fits science courses when you want repeated practice with immediate feedback, algorithmic variants, and explicit answer checking for concentrations, dilutions, and rates. After finishing, you can decide whether a task needs robust parsing and controlled grading or whether a simpler tool would serve better. Use it when students must calculate or compare values with clear units and rounding rules, and choose something else for long written explanations or simulations.
- 1.3: Key Features of WeBWorK
- Summarizes WeBWorK's key features for science prompts: PGML for readable authoring, MathObjects for robust answer parsing, randomization for algorithmic variants, and multiple interaction types via macros. After finishing, you can focus on PGML and numeric answer checking while deferring advanced features, and avoid overbuilding setup for biology workflows like concentrations and fold change. Use it as a checklist when planning a new question and deciding which features you actually need.
- 1.4: Comparing WeBWorK to other formats
- Compares WeBWorK to H5P, LMS-native quizzes, and standardized assessment packages so you can choose the right tool for each learning outcome. After finishing, you can recognize when robust parsing and algorithmic variants are worth the setup cost. Use it when deciding between WeBWorK and other formats, and consider a practical hybrid approach mixing WeBWorK for structured calculations with interactive activities for exploration.
- 1.5: Common Terms and Names
- Defines authoring terms like PG, PGML, macros, MathObjects, Context, and seed alongside platform terms like ADAPT, OPL, H5P, Commons, Insight, and Studio so you can read later sections without decoding unfamiliar language. After finishing, you can return to this page when a term blocks your progress and understand that the OPL has almost no life-science content. Use it as a quick reference when vocabulary slows you down or when you need a fixed seed for debugging.
- 1.6: Quickstart - Edit Your First Problem
- Walks you through a fast first win by copying a working PGML-first problem, changing only the story text first while keeping variable names and math intact, then previewing multiple variants. After finishing, you can copy-edit problems without breaking grading and expand into tables, multi-part prompts, and tighter answer checking. Use it when you want to ship your first working item, and use local rendering for line-level errors when ADAPT reports only a generic failure.