| name | writing_worksheet_topics |
| description | How to write standalone, printable worksheet activities for the Math Worksheet book (Grades 6–8). Focuses on quality, variety, and page efficiency — exactly 3 worksheets per topic to keep the book under 200 pages. |
| resources | ["resources/complete_example.tex","resources/activity_examples.md","resources/tikz_toolkit.md"] |
Writing Worksheet Topics — Math Worksheet Activity Book
What This Book Is
A collection of standalone, printable math activities — not drill sheets. Each topic has exactly 3 worksheets, each a different activity type (error hunts, code crackers, data analysis, scenarios, graph challenges, etc.). Every worksheet is self-contained, ~1 page, classroom-ready.
No teaching content. Students should already know the concept. The answer key teaches instead.
| Aspect | Value |
|---|
| Worksheets per topic | Exactly 3 (different activity types) |
| Answer format | \worksheetAnswer{} — bold final answer + teaching explanation |
| Page target | Under 200 pages total |
| Question numbering | \wsQ (auto-increments, resets per \worksheetHeader) |
| B&W printing | All colback=white — only title bars carry color |
How It Differs from Other Books
| Study Guide | Workbook | Puzzles | Worksheet |
|---|
| Teaching | Extensive | Quick review | None | None (answers teach) |
| Problems | \prob drill | \prob drill | Puzzle envs | Activity envs + \wsQ |
| Answers | \answer{} | \answerExplain{}{} | \puzzleAnswer{} | \worksheetAnswer{} |
Page Budget — Non-Negotiable
~44 topics × 3.5 pp = 154 pp content + 40 pp overhead = ~194 pp ✅
Stay compact: 3 worksheets/topic, \wsQ + \dotfill inline format, no tables inside activity environments, TikZ max 4cm tall, \drawSpace[3cm] not [5cm], \writeLines{3} not [6], 4–5 match pairs not 6–8.
Quality Protocol — THINK → PLAN → WRITE → VERIFY
THINK
Read the Study Guide source file. Identify 2–4 core skills, vocabulary, number ranges, common mistakes, and real-world contexts.
PLAN
Choose 3 different activity environments before writing. Target cognitive mix:
- 1 fluency (speedDrill, codeCracker, matchIt, circleIt)
- 1 analysis (errorDetective, dataAnalysis, inputOutput)
- 1 application (mathScenario, graphIt, explainIt, tableChallenge, drawSolve, sortCut)
Plan specific numbers and scenarios. Do the math before writing.
WRITE
Clear, unambiguous questions. Every question has a definite answer. Age-appropriate contexts. Bold key terms with \textbf{}. Use \wsQ for questions.
VERIFY — Mandatory
- Re-compute every numerical answer independently. Watch for: sign errors, fraction reciprocals, percent part/whole confusion, coordinate x/y mix-ups, order of operations, area formula errors.
- Re-read every explanation. Does it teach, or just restate the answer?
- Check explanation matches answer. Easy to write correct math but wrong explanation.
- Verify item counts match the targets below.
Workflow
Step 0 — Discover Topics
python3 scripts/get_chapter_topic_facts.py --chapter <N>
Returns: grade level, age range, chapter title, core/additional/modified topics, summaries.
Step 1 — Read Study Guide Source
Read each source file before writing. Extract concepts, vocabulary, difficulty, common mistakes.
| Source folder | Write to |
|---|
topics/ | topics_worksheet/ |
topics_additional/ | topics_worksheet_additional/ |
topics_modified/ | topics_worksheet_modified/ |
Step 2 — Write 3 Activities Per Topic
Follow the Quality Protocol. Same filename as the source file.
Step 3 — Compile and Verify
latexmk -xelatex -output-directory=build -interaction=nonstopmode -f tests/test_worksheet_ch<N>.tex
grep -i 'error\|undefined' build/test_worksheet_ch<N>.log | grep -v Warning | head -20
Topic File Structure
See resources/complete_example.tex for a full example. The skeleton:
\section{Topic Title}
\setcounter{wsNumber}{0}
\begin{worksheetSkills}
\begin{itemize}
\item Skill 1
\item Skill 2
\end{itemize}
\end{worksheetSkills}
\worksheetHeader{Catchy Title 1}
\begin{activityEnv}{Title}
\wsQ Question \dotfill \answerBlank[5cm]
\end{activityEnv}
\worksheetAnswer{1.~$\mathbf{answer}$. Teaching explanation.}
\worksheetHeader{Catchy Title 2}
\begin{differentEnv}{Title}
% ...
\end{differentEnv}
\worksheetAnswer{...}
\worksheetHeader{Catchy Title 3}
\begin{thirdEnv}{Title}
% ...
\end{thirdEnv}
\worksheetAnswer{...}
\worksheetDone
Critical Rules
1. Exactly 3 Worksheets Per Topic
All 3 must use different activity environments. This keeps the book under 200 pages.
2. \worksheetAnswer{} Placement
One per worksheet, placed immediately after \end{environment} (outside, not inside).
3. Answer Format: Bold Answer + Teaching Explanation
The student has just learned this topic — the answer key is a teaching moment.
Format: 1.~$\mathbf{answer}$. Method name, intermediate steps, reasoning.
- Start with bold final answer
- Name the method/rule (e.g., "Keep-Change-Flip", "inverse operations")
- Show intermediate steps
- Include a check where appropriate (
\checkmark)
- Number items
1.~, 2.~ to match \wsQ
4. No \prob, \answer{}, or \answerExplain{}{}
Use only \wsQ and \worksheetAnswer{}. No \resetProblems.
5. Item Count Targets
| Activity | Items |
|---|
| speedDrill | 4–6 |
| matchIt | 4–5 pairs |
| sortCut | 4–6 cards, 2–3 bins |
| errorDetective | 2–3 |
| mathScenario | 3–4 questions |
| inputOutput | 1–2 machines, 3–4 blanks |
| explainIt | 1–2 prompts |
| dataAnalysis | 1 data set, 3–4 questions |
| graphIt | 1 graph, 3–4 tasks |
| tableChallenge | 1–2 tables, 4–6 blanks |
| codeCracker | 4–6 |
| circleIt | 8–10 bubbles |
| colorByAnswer | 5–6 |
| drawSolve | 2–3 |
6. No Tables Inside Activity Environments
Use \wsQ + \dotfill + \answerBlank instead. Tables are OK inside tableChallenge/dataAnalysis where the table IS the content.
7. White Backgrounds
All colback=white. No \rowcolor{} on table rows.
8. Math in $...$
Use \times, \div. Bold key terms with \textbf{}.
Activity Environment Catalog
See resources/activity_examples.md for LaTeX patterns for each environment.
| Environment | Icon | Color | Best for | Key helpers |
|---|
speedDrill | Stopwatch | Orange | Fluency, quick computation | \timerBadge{N} |
matchIt | Link | Blue | Connecting concepts | \matchRow{L}{R} |
errorDetective | Magnifying glass | Red | Common mistake analysis | \errorWork{text} |
sortCut | Scissors | Orange | Classification | \cutCard{}, \wsSortBin[color]{} |
mathScenario | Globe | Teal | Real-world multi-step | \scenarioItem{name}{val} |
inputOutput | Gears | Teal | Patterns, algebraic rules | Tables with \answerBlank |
explainIt | Speech bubble | Blue | Written reasoning | \writeLines{N} |
dataAnalysis | Chart bar | Indigo | Statistics, data interpretation | Data tables |
graphIt | Chart line | Green | Coordinate plane, graphing | TikZ grids |
tableChallenge | Table | Purple | Ratio/function tables | Tables with blanks |
codeCracker | Lock | Slate | Decoding challenge | Code key + problems |
drawSolve | Paintbrush | Purple | Visual/geometric | \drawSpace[height] |
circleIt | Pointing hand | Pink | Identification | \numberBubbles{list} |
colorByAnswer | Palette | Pink | Category mapping (sparingly!) | \colorKey{ans}{color} |
Helper Commands
| Command | Purpose |
|---|
\worksheetHeader{title} | New-page banner with name/date fields |
\wsQ | Auto-numbered question |
\answerBlank[width] | Underlined blank |
\worksheetAnswer{text} | Comprehensive answer (after \end{env}) |
\worksheetSep | Decorative divider |
\worksheetDone | End-of-topic celebration banner |
Writing for the Target Audience
Get grade level and age range from the script. Never hard-code grade assumptions.
OFF-LIMITS for Grades 6–8: simple coloring pages, base-ten blocks, tracing, baby cut-and-paste, counting activities.
Works well: error analysis, code crackers, data with real-world sets, multi-step scenarios, function machines, graph interpretation, sorting with justification, explain-your-reasoning, table patterns.
Good contexts: shopping, phone plans, sports stats, recipes, travel, budgeting, science data, gaming. Avoid: counting toys, sharing stickers.
Creative Freedom
- Choose activity types that best fit the topic — no rigid template
- Invent new activity formats when the catalog doesn't fit (add to
VM_packages/VMfunWorksheet.sty)
- Use diverse character names (Mia, Leo, Zara, Marcus, Priya, Jordan, Kai, Aisha…)
- Create custom TikZ visuals (see
resources/tikz_toolkit.md)
- New environments must:
colback=white, use ws* colors, include Font Awesome icon, be tcolorbox-based + breakable, match 8pt arc + 1.5pt boxrule
What to Omit
Never use in worksheet files: \begin{conceptBox}, \begin{stepsBox}, \begin{vocabBox}, \begin{workedExample}, \begin{learningGoals}, \topicTitle{}, \begin{quickReview}, \puzzleAnswer{}, \prob, \answer{}, \answerExplain{}{}, \resetProblems, \rowcolor{}, \writeAnsQuiz.
Final Checklist
