Coding Club Teachers Guide¶

Welcome to the teacher's guide for Coding Club: How to Create, Organize, Promote and Manage a Sustainable Coding Club. This guide is written for the club leader — the teacher, librarian, parent, or engineer who both runs the club described in this book and uses several of its chapters as direct lesson material for the students who show up to meetings. No prior technical knowledge is assumed; every technical term is defined before it is used.

Two different "teaching" situations show up in this book, and this guide covers both:

Running the club itself. Most chapters (charter and safety, governance, scheduling, mentors, budgeting, equity, AI-assisted registration, and more) are operational guidance for you, the leader. There is no "class" to teach here — you read these chapters to build and sustain the club.
Teaching students directly. A cluster of chapters — computational thinking, Scratch, Python, physical computing, sensors, robots, and project kits — contain curriculum content you deliver to your own student members as actual coding club sessions. The "Suggested Classroom Use" guidance later in this guide applies to these chapters specifically.

About This Interactive Intelligent Textbook¶

What is an Intelligent Textbook?¶

An intelligent textbook is a digital textbook that goes beyond static text and images. It includes interactive simulations, self-grading quizzes, a searchable glossary, and a structured map of how concepts relate to each other. The goal is to give you — and, where you choose to use the curriculum chapters, your student members — a richer, more engaging learning experience than a traditional printed manual.

The Five Levels of Intelligent Textbooks¶

Not all digital textbooks are created equal. We categorize intelligent textbooks into five levels based on how interactive and adaptive they are:

Level	Name	Description	Example Features
Level 1	Static Digital	A PDF or basic web version of a print book	Text and images only, no interactivity
Level 2	Interactive	Adds interactive elements like simulations, quizzes, and searchable glossaries	MicroSims, self-check quizzes, concept search
Level 3	Adaptive	Adjusts content based on reader performance	Personalized learning paths, difficulty adjustment
Level 4	AI-Assisted	Includes an AI tutor that can answer reader questions	Chatbot integration, automated feedback
Level 5	Fully Adaptive AI	Continuously learns from reader interactions and optimizes the experience	Real-time content generation, predictive analytics

This textbook is a Level 2 Intelligent Textbook. It combines 129 interactive MicroSims, 35 chapter quizzes, a 657-term glossary, and a browsable learning graph — no adaptive pathing or AI tutor yet, but every chapter is built to be projected, demonstrated, and explored rather than just read.

What Makes This Textbook Different¶

Interactive MicroSims let you and your student members manipulate models directly in a browser — no software installation required
Practical, field-tested guidance — every chapter is grounded in over a decade of running real coding clubs, not theory
"Let's build something great!" framing — a warm, encouraging tone (carried by the mascot, Circuit) that treats club-building as achievable rather than overwhelming
Learning graph — a visual map showing how all 657 concepts connect and build on each other, from club charter and background checks through mentor ratios, physical computing safety, kit inventory, budgeting, and AI-assisted registration
Circuit the Robot — a friendly mascot character (called a "pedagogical agent") who guides readers through each chapter with tips, warnings, and encouragement
Completely free and open source — licensed under Creative Commons for non-commercial use

Using the Chapters¶

Chapter Structure¶

The textbook contains 35 chapters organized in dependency order — each chapter builds on concepts introduced earlier, so working through them in order is recommended for a first pass:

Chapters	Topic Area
1–2	Foundations (what a coding club is, and how AI is reshaping club management)
3–4	Club charter, safety policies, governance structure, and branding
5–8	Launching your club (gauging interest, first meeting, growth, session logistics, classroom design)
9–10	Mentors, student-to-mentor ratios, and building lasting mentor relationships
11–13	Scheduling, registration, running events, retrospectives, and term wrap-up
14–15	Curriculum: computational thinking, Scratch, Python, and challenge-card curriculum design
16–19	Curriculum: physical computing, electrical safety, sensors, motors, robots, and workshop skills
20–23	Project kits (IoT, sound, signal processing), kit inventory, and device purchasing/lifecycle
24–25	Tracking and analyzing club data
26–29	Motivation, badges, persistence, access, equity, and trust
30–31	Budgeting, fundraising, grant writing, and funding partnerships
32–34	AI agents for registration, curriculum, oversight, and inventory
35	Training mentors and building a club that outlasts you

Chapters 14–19 are the ones most club leaders will teach directly to student members as coding-club sessions; the rest guide how you build and run the club around those sessions.

What Each Chapter Contains¶

Every chapter follows a consistent structure:

YAML front matter — Metadata at the top of each chapter file (title, description, reading level, version). Readers don't see this; it's used by search engines and the website builder.
Summary — A brief overview of what the chapter covers and what you'll learn.
Concepts covered — A numbered list of the specific concepts addressed in the chapter, drawn from the learning graph.
Prerequisites — Links to prior chapters that should be completed first.
Welcome from Circuit — A mascot admonition that introduces the chapter topic in Circuit's friendly voice.
Main content — The core instructional material, written at a 10th-grade reading level. Includes tables, real-world examples, diagrams, and embedded MicroSims.
Mascot admonitions — Throughout the chapter, Circuit appears a handful of times (fewer than ten, and fewer still in shorter chapters) to highlight key insights (thinking), offer practical tips (tip), warn about common mistakes (warning), and provide encouragement on harder concepts (encourage).
Chapter Summary — A closing recap of the most important ideas, followed by a celebration from Circuit and a link to that chapter's Annotated References page.

Suggested Use¶

For the operational chapters (club foundations, charter, governance, scheduling, mentors, data, budgeting, equity, AI agents):

Before you act: Read the relevant chapter before making a decision it covers — for example, read the mentor ratio chapter before you set your own club's ratio, or the charter chapter before drafting your own.
Reference, not cover-to-cover: Once you've read the book once, treat it as a reference. Jump to the chapter you need the week you need it.
Use the quiz as a self-check: Each operational chapter's quiz is a fast way to confirm you understood the chapter before you apply it.

For the curriculum chapters (14–19: computational thinking, Scratch, Python, physical computing, sensors, robots):

Before your session: Skim the chapter and try the MicroSims yourself first, so you know what your student members will see.
During your session: Project the MicroSims on a screen for whole-group demonstrations. Ask students to predict what will happen when you change a slider or setting, then test their prediction together.
After your session: Use the chapter's quiz questions informally as review, or adapt them into your own warm-up activity for the next meeting.
Pacing: Each curriculum chapter is designed for roughly 2–3 club sessions. Chapters with more MicroSims or hands-on kit work may take longer.

Using the MicroSims¶

What is a MicroSim?¶

A MicroSim (short for "micro-simulation") is a small, interactive simulation that runs directly in a web browser. No software installation is required — MicroSims work on any device with a modern web browser (Chrome, Firefox, Safari, Edge).

Each MicroSim lets you manipulate one or more variables (using sliders, buttons, or drag-and-drop) and immediately see how the model responds. This "learn by doing" approach builds intuition faster than text alone — whether you're testing a room layout for your own club or showing a student member how a servo's pulse width controls its angle.

How MicroSims Are Embedded¶

MicroSims appear within chapter text as rectangular interactive areas. They are embedded using iframes — a web technology that displays one web page inside another. You don't need to understand how iframes work; they load automatically when you view a chapter page.

Types of MicroSims¶

The textbook includes 129 MicroSims built with different visualization technologies:

Technology	What It's Good For	Example MicroSims
p5.js	Interactive animations with sliders and buttons	Seven Segment Display Explorer, Servo Angle and Pulse Width Explorer, Blinking LED Breadboard Circuit
Chart.js	Bar charts, line charts, dashboards	Club Health Metrics Dashboard, Attendance and Enrollment Trend Explorer, Anonymized Attendance Chart
vis-network	Network diagrams showing connections	Coding Club Ecosystem Map, Club Governance Map, the Learning Graph Viewer

Tips for Using MicroSims in Sessions¶

Project them on a screen — MicroSims are designed to be visible on a projector. Have students call out predictions before you move a slider.
Let students explore independently — After a demonstration, give students 5–10 minutes to experiment on their own devices.
Use the "Reset" button — Every MicroSim has a reset button. Encourage students to reset and try different scenarios.
Connect to the text — Each MicroSim is placed near the concept it illustrates. After exploring the sim, revisit the surrounding text together.
Offline access — MicroSims require an internet connection unless you have built the site locally (see "Customizing Your Own Textbook" below).

Circuit's Tip: Embed MicroSims Anywhere!

Circuit shares a tip You can add any MicroSim to any web page — a Google Site, a WordPress blog, a school LMS like Canvas or Schoology, or even a plain HTML file. Just paste a single line of HTML:

<iframe src="https://dmccreary.github.io/coding-club/sims/YOUR-MICROSIM-NAME/main.html"
    width="100%" height="450px"
    scrolling="no">
</iframe>

Replace YOUR-MICROSIM-NAME with the name of any MicroSim from the MicroSims list. That's it — one line of code and your club has an interactive simulation on any page you control.

MicroSim Specifications¶

Within each chapter, you'll find a collapsible details section below each MicroSim labeled with its name. Click to expand and see the full specification including:

Bloom's Taxonomy level — What cognitive level the MicroSim targets (Remember, Understand, Apply, Analyze, Evaluate, Create)
Learning objective — What a reader or student should be able to do after using the MicroSim
Interactive controls — What sliders, buttons, and inputs are available
Default parameters — The starting values when the MicroSim loads

These specifications are useful for session planning and for understanding the pedagogical intent behind each simulation.

Using the Glossary¶

What is the Glossary?¶

The glossary is an alphabetical list of all key terms used in the textbook — 657 terms in total — each with a precise, concise definition. It serves as a quick-reference dictionary for anyone encountering unfamiliar vocabulary, whether that's a club-management term like "backpackability" or a hardware term like "pulse width modulation."

How to Access the Glossary¶

Click "Glossary" in the left navigation sidebar from any page
Use the browser's built-in search (Ctrl+F on Windows/Linux, Cmd+F on Mac) to find a specific term on the glossary page
Use the site-wide search bar at the top of any page to search for a term across the entire textbook

Tips for Using the Glossary¶

Vocabulary preview — Before a session on a new curriculum chapter, have students look up the key terms in the glossary to build familiarity.
Definition matching — Create a warm-up activity where students match glossary definitions to terms from the current session's topic.
Student-generated definitions — After a session, have students write their own definitions, then compare with the glossary.
Your own reference — For the operational chapters, the glossary is a fast way to confirm you're using a term (like "3:1 ratio" or "backpackability") the same way the book does.

Using the FAQ¶

What is the FAQ?¶

The FAQ (Frequently Asked Questions) is a curated list of 70 common questions about running and teaching in a coding club, organized by topic. Each question includes a clear, concise answer written at the same reading level as the chapters.

Tips for Using the FAQ¶

Discussion starters — Pick 2–3 FAQ questions at the start of a mentor meeting or club-leader training session and discuss before revealing the answer.
Quick answers — Point to the FAQ when a new mentor or parent has a question outside of a scheduled meeting.
Extension reading — The FAQ often covers angles not addressed in the main chapter text, making it good supplementary material.

Using the Quizzes¶

What Are the Quizzes?¶

Each chapter has an accompanying quiz page with multiple-choice questions designed for self-assessment — 35 quizzes, 350 questions total. Quizzes test understanding of the concepts covered in that chapter and are aligned to specific items from the learning graph.

How Quizzes Work¶

Quizzes are accessed by clicking the "Quiz" link under each chapter in the left navigation
Each quiz contains multiple-choice questions at varying Bloom's Taxonomy levels
Questions are presented as expandable sections — click "Show Answer" to reveal the answer and explanation after attempting the question
Quizzes are not graded automatically — they are designed as formative self-check tools, not summative assessments

Tips for Using Quizzes¶

Your own comprehension check — After reading an operational chapter, take its quiz to confirm you understood it before applying it to your club.
Curriculum-chapter review — For chapters 14–19, adapt a few quiz questions into an oral warm-up or exit ticket for your student members.
New-mentor onboarding — Have incoming mentors take the quizzes for the operational chapters most relevant to their role (charter, safety, mentor ratios).
Custom assessments — Use the quiz questions as a bank to build your own review materials. The questions are openly licensed (see "Understanding the License" below).

Bloom's Taxonomy Levels¶

Each quiz question is tagged with a Bloom's Taxonomy level. Bloom's Taxonomy is a framework that classifies thinking skills from simple to complex:

Level	Name	What It Means	Example Verb
L1	Remember	Recall facts and definitions	Define, list, name
L2	Understand	Explain concepts in your own words	Explain, describe, compare
L3	Apply	Use concepts to solve problems	Calculate, demonstrate, solve
L4	Analyze	Break down and examine relationships	Differentiate, organize, compare
L5	Evaluate	Make judgments based on criteria	Assess, argue, justify
L6	Create	Produce original work or solutions	Design, construct, propose

A well-balanced quiz includes questions across multiple levels, so a chapter's quiz can double as a quick way to gauge whether you (or a student, for curriculum chapters) have moved beyond recall into application.

Using the References¶

What Are the References?¶

Each chapter has an accompanying references page ("Annotated References," linked at the end of every chapter) with a curated list of high-quality sources for further reading. References prioritize Wikipedia articles for accessibility and reliability, supplemented by authoritative books, research, and organizations like the Raspberry Pi Foundation and CoderDojo.

How References Are Organized¶

Each reference includes:

Title — The name of the source
URL — A clickable link to the source
Relevance — A brief description of why this source is useful and how it connects to the chapter content

A Note About Link Rot¶

Link rot is when a web link (URL) stops working because the page has been moved, renamed, or deleted. This is a common problem with any resource that links to external websites. While we prioritize Wikipedia (which has very stable URLs), some links may become outdated over time.

If you encounter a broken link:

Try searching for the article title on the source website
Use the Wayback Machine to find archived versions of the page
Report the broken link using GitHub Issues (see "Feedback" below)

Feedback¶

Reporting Issues and Suggestions¶

This textbook is an open-source project hosted on GitHub, a website where software and content projects are developed collaboratively. You don't need to understand programming to report a problem or suggest an improvement.

What is a GitHub Issue?¶

A GitHub Issue is like a support ticket — it's a way to report a bug, suggest an improvement, or ask a question. Each issue gets a unique number and can be discussed by the project team and community.

How to Submit Feedback¶

Go to the textbook's GitHub repository: dmccreary/coding-club
Click the "Issues" tab at the top of the page
Click the green "New issue" button
Give your issue a clear title (e.g., "Broken link in Chapter 5 references" or "Suggestion: Add MicroSim for topic X")
In the description, provide as much detail as possible:
- Which page or chapter has the problem
- What you expected to see vs. what you actually see
- Your browser and device (if relevant)
Click "Submit new issue"

You will need a free GitHub account to submit issues. If you prefer not to create an account, you can email feedback to the author using the Contact page.

Types of Feedback Welcome¶

Typos and errors — factual mistakes, spelling errors, broken formatting
Broken links — URLs that no longer work
MicroSim bugs — simulations that don't load or behave unexpectedly
Content suggestions — topics that should be covered, examples that could be improved
Accessibility issues — content that is difficult to read or navigate for readers with disabilities

Understanding the License¶

What is a Creative Commons License?¶

A license is a legal document that explains what others are allowed to do with a piece of work. A Creative Commons (CC) license is a standardized, easy-to-understand license used for educational and creative content. It tells you exactly what permissions you have without needing a lawyer.

This Textbook's License¶

This textbook uses the CC BY-NC-SA 4.0 license. Here's what each part means:

Code	Full Name	What It Means
CC	Creative Commons	A standard open license
BY	Attribution	You must give credit to the original author
NC	Non-Commercial	You cannot use the material to make money
SA	Share-Alike	If you modify the material, you must share it under the same license
4.0	Version 4.0	The version of the license (the current standard)

What You CAN Do¶

Copy the entire textbook or individual chapters for your own club or your student members
Share the textbook link with other club leaders, mentors, or parents
Print chapters, challenge cards, or forms for club use
Modify the content — add your own examples, remove sections, change the order
Translate the content into other languages
Create derivative works — build your own version of the textbook based on this one

What You CANNOT Do¶

Sell the textbook or charge students for access
Remove attribution — you must credit the original author (Dan McCreary)
Use a different license — if you modify and share, it must remain CC BY-NC-SA 4.0
Claim it as your own work — the attribution requirement means you must acknowledge the original source

For the full legal text, see the Creative Commons License page.

Customizing Your Own Textbook¶

One of the most powerful features of this textbook is that you can create your own customized version — for example, to match your own club's name, colors, or local kit inventory. This section explains how, step by step.

Key Technical Terms¶

Before we begin, here are some terms you'll need to understand:

Repository (repo) — A folder on GitHub that contains all the files for a project. Think of it as the project's home directory.
Git — A version control tool that tracks changes to files. It lets you see what changed, when, and by whom.
Clone — Making a complete copy of a repository on your own computer.
Fork — Making a complete copy of a repository on your own GitHub account (stays on GitHub, not your computer).
MkDocs — The software that converts the textbook's markdown files into a website. You don't need to learn MkDocs deeply — just enough to make basic changes.
Markdown — A simple text formatting language. If you can write an email, you can write Markdown. **bold** makes bold, # Heading makes a heading, and - makes a bullet point.
mkdocs.yml — The main configuration file for the textbook website. It controls the site title, navigation structure, colors, and which features are enabled.

Step 1: Create a GitHub Account¶

If you don't already have one, go to github.com and create a free account.

Step 2: Fork or Clone the Repository¶

Option A: Fork (easier, stays on GitHub)

Go to dmccreary/coding-club
Click the "Fork" button in the upper-right corner
This creates a copy in your own GitHub account that you can edit

Option B: Clone (more control, works on your computer)

Install Git on your computer (git-scm.com)
Open a terminal (Command Prompt on Windows, Terminal on Mac)
Run this command:

git clone https://github.com/dmccreary/coding-club.git

This downloads the entire textbook to your computer.

Step 3: Make Changes¶

All content files are in the docs/ folder. They are written in Markdown (.md files) — plain text files with simple formatting. You can edit them with any text editor.

Changing the Title and Description¶

Open mkdocs.yml and edit these lines:

site_name: "Your Custom Textbook Title"
site_description: "Your description here"
site_author: "Your Name"

Changing the Colors¶

In mkdocs.yml, find the palette section:

theme:
  palette:
    primary: 'blue'    # Change to: red, purple, teal, etc.
    accent: 'amber'     # Change the accent color

MkDocs Material supports these primary colors: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey.

Changing the Logo or Mascot¶

Replace the files in docs/img/mascot/ with your own character's poses, or point theme.logo in mkdocs.yml at a different image (approximately 128x128 pixels).

Step 4: Preview Your Changes Locally¶

Install Python (version 3.8 or newer) from python.org
Install MkDocs and the Material theme:

pip install mkdocs mkdocs-material

Navigate to the project folder and start the preview server:

cd coding-club
mkdocs serve

Open your browser to http://127.0.0.1:8000/coding-club/ to see your customized version

The preview server watches for file changes. When you edit and save a Markdown file, the page automatically refreshes in your browser.

Step 5: Publish Your Version¶

To publish your customized textbook as a free website using GitHub Pages:

mkdocs gh-deploy

This command builds the website and publishes it to https://YOUR-USERNAME.github.io/coding-club/. The process takes about 1–2 minutes.

Customizing Your Analytics¶

What is Web Analytics?¶

Web analytics is the process of measuring how visitors use a website — which pages they visit, how long they stay, and where they come from. For an intelligent textbook, analytics can help you understand which chapters readers use most, which MicroSims they interact with, and where they might be struggling.

Google Analytics¶

This textbook includes Google Analytics — a free service from Google that tracks website visits. The author's analytics property is already configured, but if you create your own fork, you'll want to set up your own.

Setting Up Your Own Google Analytics¶

Go to analytics.google.com and sign in with a Google account
Create a new property (Google's term for a tracked website)
Google will give you a Measurement ID — a code that looks like G-XXXXXXXXXX
In your mkdocs.yml, update this section:

extra:
  analytics:
    provider: google
    property: G-YOUR-MEASUREMENT-ID

Rebuild and deploy your site. Analytics data will start appearing within 24–48 hours.

What You Can Learn from Analytics¶

Which chapters are most/least visited — helps you identify where readers might be skipping content
Average time on page — longer times may indicate engagement or confusion
Device breakdown — what percentage of readers use phones vs. computers
Geographic distribution — where your readers are accessing from
Search terms — what people search for on your site

xAPI Monitoring (Advanced)¶

xAPI (Experience API, also called "Tin Can API") is an advanced standard for tracking detailed learning activities — not just page views, but specific interactions like "student moved a slider to position X" or "student answered quiz question 3 correctly."

What is an LRS?¶

An LRS (Learning Record Store) is a database that stores xAPI learning records. Think of it as a specialized analytics system designed specifically for education. If you use an LRS, you can track granular learning data for your student members.

Important: Regulatory Considerations¶

Before collecting student-specific learning data — for example, tracking individual student members' progress through the curriculum chapters — be aware of these regulations:

FERPA (Family Educational Rights and Privacy Act) — U.S. federal law that protects student education records. If you collect data that can identify individual students, you must comply with FERPA.
COPPA (Children's Online Privacy Protection Act) — U.S. federal law that applies to children under 13. Most coding club members fall under this law.
State laws — Many U.S. states have additional student privacy laws.
GDPR (General Data Protection Regulation) — European Union law that applies if any of your students are in the EU.

Recommendation: The Google Analytics setup described above is anonymous by default — it tracks aggregate page views, not individual students. This is the safest approach. If you want individual student tracking via xAPI, consult your school or district's data privacy officer before proceeding. Chapter 24, Tracking Student Data and Managing Club Communication, covers this topic in depth.

The Learning Graph¶

What is a Learning Graph?¶

A learning graph is a visual map showing how concepts in the textbook depend on each other. It is structured as a DAG (Directed Acyclic Graph) — a diagram where arrows show which concepts must be understood before others.

For example, understanding "background checks for volunteers" requires first understanding "club charter," and understanding "AI-customized curriculum" requires first understanding "computational thinking." The learning graph makes these dependency chains visible across all 657 concepts.

How Club Leaders Can Use the Learning Graph¶

Prerequisite checking — Before teaching a curriculum concept, verify that students have covered its prerequisites
Remediation — If a student struggles with a concept, trace back to its prerequisites to find the gap
Club planning — Compare the learning graph to your own club's yearly plan to identify coverage gaps
Onboarding new mentors — Point new mentors to the graph so they see how the topic they'll help with connects to the rest of the club's operations

The interactive Learning Graph Viewer is available in the "Learning Graph" section of the left navigation.

Circuit: Your Pedagogical Agent¶

What is a Pedagogical Agent?¶

A pedagogical agent is a character that appears throughout a textbook to guide readers. Research shows that pedagogical agents improve engagement and perception of learning — a phenomenon called the persona effect.

How Circuit Appears¶

Circuit — a small, sky-blue robot with a glowing amber antenna — appears as colored callout boxes (called admonitions) throughout each chapter. There are seven types:

Type	Color	Purpose	Frequency
Welcome	Green	Introduces the chapter	Every chapter opening
Thinking	Orange	Highlights key insights	1–4 per chapter
Tip	Green	Shares practical advice	As the material warrants
Warning	Red	Alerts to common mistakes	As the material warrants
Encourage	Blue	Supports on harder concepts	Where readers may struggle
Celebration	Purple	Celebrates progress	Every chapter ending
Neutral	Gray	General notes	Rarely

Circuit appears fewer than ten times in any chapter, and appears less often in shorter chapters. Mascot admonitions are never placed back-to-back.

Tips for Club Leaders¶

Read Circuit's tips aloud — They're written in a conversational tone that works well when spoken to your student members during a curriculum chapter session.
Use as discussion prompts — Circuit's "thinking" admonitions highlight the most important insight in each chapter; good candidates for a quick group discussion.
Encourage struggling students — Point students to Circuit's "encourage" admonitions when they're frustrated with a concept like the jump from Scratch to Python.
Model the voice — Circuit calls club members "builders" or "makers." Borrowing that language yourself reinforces the book's tone during your own sessions.