--- title: "Computing Refresh for Adults" author: "Michael Gannotti" lang: en-US date: "13 October 2026" --- ![Cover: COMPUTING REFRESH FOR ADULTS, Michael Gannotti](art/cover-titled.jpg){width=100%} \newpage # Computing Refresh for Adults {.unnumbered} Michael Gannotti *A guide for adults learning computing for themselves and for parents refreshing to teach or co-learn with their kids: specs, Python, testing, data and SQL, the web, the command line and Git, home security, AI, and honest records. Book 4 of the SMF WisdomForge Computing series.* Illustrated edition, 13 October 2026. Notes run in one series at the back; the superscript numbers link to them. The images are original still lifes, with no people and no brands. # Contents {.unnumbered} - Welcome - How to Use This Book This Week - If You Only Remember Five Things - The Computing Hour - Chapter 1 — Coming Back to Computing: Specs, Algorithms, and a Plan You'll Keep - Chapter 2 — Python as a Working Tool - Chapter 3 — Testing and Debugging: Proof Before Pride - Chapter 4 — Data: Spreadsheets, Questions, and SQL - Chapter 5 — Building for People: The Web - Chapter 6 — The Command Line and Git: Save Points and Grown-Up Tools - Chapter 7 — Systems and Security at Home: Backups, Passwords, and the Family Rule - Chapter 8 — Working With AI as an Adult Learner: Where It's Wrong and Whose Work It Is - Chapter 9 — Records: Your Learning Log and Portfolio—and Your Teen's Transcript - Chapter 10 — Resources - A Note on Sources - Notes \newpage # Welcome *An illustration, not a reported family:* Picture a parent at the kitchen table after the kids are asleep, a notebook open, trying to guess what four lines of Python will print. The guess is written in pencil before the laptop is opened. When the screen disagrees, the parent doesn't sigh; they lean in, because now there's a clue. That scene is the whole book in small. Not the late hour—you'll find your own time—but the order of things. A guess first. Then the computer. Then a calm look at the difference. ## Who this book is for This book is for two kinds of readers, and some of you are both. The first is a parent who wants to teach computing at home, or learn it alongside a child, and who would like to feel steady doing it. Maybe your seven-year-old has discovered block coding and keeps asking what the blocks "really" do. Maybe your thirteen-year-old has moved to typed Python and you'd like to read over a shoulder without bluffing. Maybe your sixteen-year-old wants a transcript line that means something, and you're the one who has to sign it. The second is an adult learning for yourself. You might be curious about a career change, or retired with time at last, or simply tired of not knowing what a program does when it runs. You may never have written a line of code. You may have taken a programming class long ago and kept nothing but the memory of a semicolon. Both of you are welcome here, and neither of you is behind. You'll read the same chapters. Each teaching chapter teaches you first, as an adult learner, and then offers a short section called "Coaching your kids at every age" that turns the same skill into something you can do with a child of five, a twelve-year-old, or a teen. If there are no children in your life right now, that section is optional. ## Rust is ordinary Many adults feel rusty. That's the normal starting point, not a verdict. Here is what the evidence on learning to program actually suggests: the difference between beginners who make progress and beginners who stall is mostly a difference in strategy—planning before typing, tracing what the code will do, testing it, and changing one thing at a time—rather than some rare gift.^[1](#note-1)^ Strategies can be taught. They can be practiced in twenty minutes on a Tuesday. This book is built from them. ## The line the whole book runs on **Specify it small; predict before you run; debug before you rewrite; explain it before you call it yours.** - **Specify it small.** Say what you want before you build it, in writing, in a size you can finish this week. - **Predict before you run.** Write your guess before the computer answers. A wrong guess is the most useful thing that can happen in a session; it shows you exactly where your picture and the program part ways. - **Debug before you rewrite.** A bug is a clue. Starting over throws the clue away. - **Explain it before you call it yours.** If you can't explain every line, it isn't yours yet—whoever or whatever wrote it. The last three clauses are the same ones the earlier books in this series teach to children and teens, word for word. That's deliberate. When your child hears "predict before you run," you'll know it from the inside. ## What a good session looks like A good session is short and complete. You write a few lines saying what you'll build today and how you'll know it's done. You write down what you expect to happen. You build a little and test it. When something surprises you, you write down what you expected, what happened, and the one change you'll try. Then you say what you did, name any help you used, and save your work in two places. That's **The Computing Hour**, and it has its own section right after the front matter. The name is the series' word; your sessions will often run fifteen or twenty-five minutes, and that counts. ## What this book won't do This book won't hand you a 180-day script. It gives you this week's sessions and a menu of activities, and trusts you to choose. It won't sell you a course, and it doesn't rank products. Tools are named plainly when they fit, with a reminder to check the current version. It won't promise you a job. Chapter 9 talks honestly about work, as a possibility with real costs in time, not as a guarantee. It won't print you a certificate. Your records will be real: a dated learning log, a portfolio, and an honest note on every project about what help you used. And it won't promise that programming will make you or your children cleverer in general. Learning to program teaches programming, which is plenty. Other benefits are possibilities, and we'll treat them that way. ## Where this book sits This is the fourth and final book in the SMF WisdomForge Computing series. *Computing for Little Thinkers* (ages 5–10) asks the parent to be a literal robot and a patient question-asker: "What will I do if you tell me that?" *Computing for Young Minds* (ages 11–14) asks the parent to check predictions and read the Debug Log. *Computing for Emerging Adults* (ages 15–18) asks the parent to be first user, safety-keeper, and records-keeper while the teen runs the work. This book is the one for you. It teaches the same habits at an adult's pace, so that whichever rung your child is on, you can stand beside them—and so that, if you're learning for yourself, you have a complete path of your own. You don't need to be ahead of your child at any rung. You need to ask good questions, wait, and say "I don't know yet—let's find out." This book will help you do all three. Turn the page, read How to Use This Book This Week, and plan three short sessions. By Sunday you'll have a dated baseline page, a reason written on a card, and your first prediction checked against a real program. — Michael Gannotti \newpage # How to Use This Book This Week You can start this book tonight with a pencil. Nothing in the first week needs more than a notebook, a deck of index cards, and—on the third day—a computer you're allowed to install a program on. ## Two roads through the book **If you're learning for yourself,** read Chapters 1 through 8 in order. Each one builds on the last: specs and algorithms, then Python, then testing, data, the web, the command line and Git, household security, and working with AI. Chapter 9 shows you how to keep records as you go, and Chapter 10 helps you find tools and people. If you're learning for yourself, the coaching sections are optional—some readers use them with a nephew, a grandchild, or a friend. **If you're refreshing to teach or co-learn,** take the same road in the same order, and read each chapter's "Coaching your kids at every age" section too. Then keep the sibling book for your child's rung nearby: *Computing for Little Thinkers* for ages 5–10, *Computing for Young Minds* for 11–14, *Computing for Emerging Adults* for 15–18. You don't need to finish this book before your child starts theirs. Most parents run a few weeks ahead on the habits—predicting, logging, explaining—and learn the content alongside. ## Place yourself by what you can do today Start with START-01 The Baseline Page in Chapter 1. It asks you to write, from memory and with no help, what you can already read, trace, and build. Date it. That page—not a class you took years ago, and not what you think you ought to know—tells you where to begin. If your baseline shows you can already write a small Python function and test it, you can move quickly through the early parts of Chapter 2. If it shows a blank page, you're in exactly the right place to start at Chapter 1's first try-it. Each chapter ends with "What 'done enough' looks like," a short checklist. Done enough means ready to move on, not finished forever. ## This week Three sessions and one optional extra. Each uses cards from the activity bank; the codes and names match the bank exactly, so you can find them again. **Day 1 (desk, about 30 minutes).** START-01 The Baseline Page, then START-02 Why Card: one sentence each on why you're learning, for whom, and what you'll build first. Tape the card inside the front cover of your notebook. **Day 2 (micro, about 15 minutes).** START-03 Cue and Kit: choose a fixed cue (after the morning coffee, after school drop-off, after the dishes) and set out a notebook, a pencil, and one saved file. Then PLAN-01 The Week on One Card: next week's two or three sessions, each with a day, a length, and the one thing you'll build. **Day 3 (desk, about 40 minutes).** START-04 Set Up a Clean Workspace: install a beginner-friendly Python editor, make one learning folder, and save a first file in two places. Then PY-01 Predict the Output—write what a short program will print, run it, and compare. Finish with LOG-01 The Learning Log Page: the date, the length, what you specified, predicted, and built, and the help you used. **Weekend (optional micro).** SPEC-03 The Literal Reader with a partner or your child: they follow your written steps for making a sandwich with total literalness, and you repair every ambiguity. It's the funniest fifteen minutes in the book, and it teaches the first chapter's biggest idea. **Parents:** add one coaching move from the chapter your child is working in. COACH-02 Ask for the Prediction is always safe: before anything runs, ask your child to write what they think it will do. ## The activity bank is a menu The book's 100 activities are coded cards—START, SPEC, PY, TEST, and so on—and every chapter points to the ones that belong to it. Each card names its context, its time, and which rung of the ladder it helps you support: yourself, all ages, or a specific age band. You won't do all of them. Pick the ones that fit the week you actually have. The contexts are the same everywhere in the book: - **Micro** (15–25 minutes): a lunch break, a wait at practice, a ride where someone else is driving. Paper cards fit here. - **Desk** (30–50 minutes): an evening at the table. - **Deep** (60–90 minutes): a weekend block, for projects. Two or three sessions a week make a full week. On a hard week, one micro session on paper keeps the habit alive. ## How long a pass takes This is a planning estimate, not a research finding. At two or three sessions a week, most adults can expect roughly three weeks for Chapter 1, four or five for Chapter 2, three for Chapter 3, four for Chapter 4, three or four for Chapter 5, two or three each for Chapters 6 and 7, and about three for Chapter 8. That adds up to roughly six to nine months for a first full pass, with the record-keeping practices of Chapter 9 running all along. Faster or slower is fine. ## Learning alongside your kids COACH-06 Co-Learning Hour is a deep session you run side by side with a child or teen on the same small spec, each with your own file and your own log. It's the best single thing a parent can do with this book, and it works even when your teen is ahead of you: you become the spec reader and the first user, and they get the strongest possible check of their own understanding—teaching it to you. For the whole household, FAM-05 Screens on Purpose is a short family media plan: screens open for a job and close when it's done, and sleep and meals are protected. Your learning sessions follow the same rule. ## Special situations - **Shift work or caregiving.** Micro sessions on paper count. In a hard season, the log *is* the week. - **Low vision or other access needs.** Larger editor fonts, a screen reader, and keyboard navigation all work with the tools in this book. Chapter 5's accessibility pass applies to your own setup as much as to a web page. - **One shared family computer.** Give each person a separate user account, and keep a teen's portfolio on a family drive. **The Computing Hour**'s AI box has one more caution for shared computers. - **A teen who's ahead of you.** Wonderful. Ask them to teach you one thing a week. - **Learning through work.** Follow your employer's rules on tools and data, especially before using AI tools with work code. Now turn to If You Only Remember Five Things. It's short on purpose. \newpage # If You Only Remember Five Things If a busy month swallows the rest of this book, keep these five. They're the habits underneath every chapter, and they're the same ones you'll ask of your kids. ## 1. Say what you want before you build it—small enough to finish. A few written lines—what it's for, what goes in, what comes out, and what "done" means—will save you more time than any shortcut you'll ever learn. Small is the adult's secret: a program you finish this week teaches more than a grand one you abandon in March. If the spec won't fit on one page, the project is too big for now; cut it until it does. ## 2. Guess what will happen before you run it, and write the guess down. The guess turns a run into an experiment. When the computer agrees, you've confirmed your picture; when it disagrees, you've found the exact spot where your understanding needs work, which is the most valuable thing a session can produce. A prediction can be one line in pencil. It still counts. ## 3. When it breaks, change one thing and log it. Expected, actual, your guess, one change, the result. Five lines on a page will calm a frustrating evening and, a month later, show you how much you've learned. Three changes at once only tells you that something, somewhere, did something. And when you're tempted to delete it all and start fresh, log the bug first; the clue is worth more than the clean page. ## 4. Call it yours only when you can explain every line; name the help you used. A tutorial, a friend, the official documentation, an AI tool—all of it is fine to use, and none of it is shameful. Write "Help I used: …" every time, even when the answer is "none," and keep only the code you can explain line by line. That rule protects your learning, and it's the same rule you'll hold your teen to—so it helps to have kept it yourself. ## 5. Your kids need your questions more than your answers. "What do you think it'll do?" "Show me where it surprised you." "I don't know either—let's find out." You don't have to be ahead of your child at any age. You have to ask, wait, and hand the work back. Everything else in this book—Python, data, the web, Git, security, AI—is these five habits applied to a new kind of problem. When a chapter feels heavy, come back to this page and ask which of the five you skipped. \newpage # The Computing Hour ![A desk by a window set for the Hour: an open laptop showing indented colored bars, a handwritten spec page, an open Debug Log notebook, an index card, a pencil and a mug — still life, no people, no logos, no readable text.](art/computing-hour-setup.jpg){width=100%} **The Computing Hour** is the session this whole book runs on. It has five steps, the same five every time, and you run all of them yourself. "Hour" is the series' word, not a clock promise: your sessions will often be fifteen or twenty-five minutes, sometimes fifty, now and then ninety. Learn the shape this week, and every chapter after this will slot into it. **Specify it small; predict before you run; debug before you rewrite; explain it before you call it yours.** ## The five steps | Step | What you do | Micro (15–25) | Desk (30–50) | Deep (60–90) | |---|---|---|---|---| | **Specify** | Write the goal, the input, the output, and the done line | 2–3 min | 5 min | 5–10 min | | **Predict** | Write what you expect to happen before running | 1–2 min | 2–3 min | 3–5 min | | **Build and Test** | Write a little, run it, check it against your examples | 8–15 min | 15–30 min | 35–60 min | | **Debug and Log** | Expected / Actual / Guess / One change / Result | 2–3 min | 5–8 min | 8–12 min | | **Explain and File** | Say or write the exit line; save in two places | 1–2 min | 3–4 min | 4–5 min | **Specify.** A spec is a short written description of what a program must do, with examples and a line saying what "done" means. For a micro session it can be three lines on an index card: "Today I'm building a tip splitter for our dinner group. It takes the bill and the number of people and gives back each share. It's done when 60 split three ways gives 20." Later in a project, Specify is a two-minute reread and one updated line. Chapter 1 teaches specs in full. **Predict.** Before you run anything, write one line: "When I run it with ___, I expect ___." This feels slow for about a week. Then it starts to feel like the point. A wrong prediction isn't a failure; it's a map of the exact place where your picture of the program and the program itself disagree. **Build and Test.** Write a few lines, run them, and check the result against the examples in your spec. Then a few more. Small steps keep surprises small. From Chapter 3 on, "test" means a written check—code that compares what the program does with what it should do—but on day one, a test can be you looking at the output and your spec side by side. **Debug and Log.** When something surprises you, reach for the pencil before the keyboard. Write what you expected, what actually happened, your best guess at why, the one change you'll try, and what happened when you tried it. That's a Debug Log entry, and it gets its own section below. **Explain and File.** End by saying or writing the exit line, then save your work in two places—your learning folder and a backup. Filing is part of the step, not an afterthought; Chapter 9 turns these files into a portfolio without any extra work. ## The exit line Every session ends with the same five-part sentence, said aloud or written in your log: "I specified… I predicted… It did… Next I'd change… Help I used: …" For example: "I specified a tip splitter for three people. I predicted 60 would give 20. It did, but 50 gave 16.666666666666668. Next I'd change it to round to cents. Help I used: none." "Help I used" gets filled in every time, even when the answer is "none." A tutorial, a friend, the official documentation, an AI tool, your teenager—all of it counts, and none of it is shameful. The habit matters because you'll ask the same of your kids, and because six months from now you'll want to know what you could do alone. ## The Debug Log The Debug Log is a notebook (or a file) with one page per bug, dated. Each page has five fields, always in this order: - **Expected** — what you thought would happen - **Actual** — what did happen, copied exactly - **Guess** — your best reason for the difference - **One change** — the single thing you'll try - **Result** — what happened after that change Here's a filled page from a micro session (an illustration): > **Tue, 7:10 p.m. (micro)** > **Expected:** 20 for each of 3 people from a 60 bill. > **Actual:** 20.0 > **Guess:** dividing always gives a decimal number in Python. > **One change:** none needed—20.0 equals 20. Updated my spec to say "20.0 is fine." > **Result:** spec now matches; test passes. Notice that the change was to the spec, not the code. That happens more than you'd think, and it's a good sign: it means you're checking your intentions, not just your typing. BUG-02 The Debug Log Page is the bank card for this habit; Chapter 3 builds it into a full testing practice. ## Contexts, not ages Your sessions come in three sizes, chosen by the time you have, not by how advanced you are. - **Micro (15–25 minutes)** fits a lunch break, a wait at swim practice, or a train ride. Paper work fits here beautifully: a trace, a test table, a spec, a log review, PY-01 Predict the Output. - **Desk (30–50 minutes)** fits an evening at the table. Most worked sessions in this book are desk sessions: one new idea, practiced until it works. - **Deep (60–90 minutes)** fits a weekend morning. Use it for projects, and take a short break in the middle—stand up, refill the mug, look at something far away. Two or three sessions a week make a full week. As a planning estimate, that's about two to three hours a week for most adults. Less is still progress. PLAN-01 The Week on One Card is the two-minute way to plan them: day, length, and the one thing you'll build. ## The rescue order Everyone gets stuck. The rescue order is what you do next, in order, so that being stuck turns into learning rather than flailing. **For yourself:** 1. **Reread your spec.** Half of all stuck moments are a fuzzy spec. Is the done line actually written? 2. **Wait.** Set a five-minute timer and trace the code by hand, line by line, on paper. Most bugs surrender here. 3. **Hint.** Check your own notes and the official documentation. 4. **Worked example.** Build a short example of the idea in a separate scratch file—a few lines, nothing else—until it does what you expect. 5. **Back to your own file.** Bring what you learned home. Ask a person or a tool after the timer, not before, and log that you did. **With a child** (the rule the whole series uses): 1. **Ask:** "What did you think it would do?" 2. **Wait.** Really wait. Count to ten in your head if it helps. 3. **Hint:** "Look at line three again." 4. **Short demo on your own copy**—never on theirs. 5. **Hand it back.** COACH-03 The Rescue Order is the bank card for rehearsing the child version. It's harder than it looks, mostly because the urge to grab the mouse is strong. ## When the Hour goes wrong - **No time.** Do a micro session on paper: one trace, one prediction, one log line. It counts. - **Stuck the whole session.** Log it and stop. Write Expected, Actual, and your best Guess, and leave One change blank for next time. A logged stuck session is progress; you'll start the next one exactly where the problem is. - **Too tired.** Do AS-01 Cold Trace only—trace a short program and predict its output—or simply reread last session's log. - **The session turned into tutorial-following.** You typed what a video typed and it worked, but you can't say why. Next time, change one thing in the example and predict what will happen before you run it. - **You missed a week.** Pick up at your cue. One missed session doesn't undo a habit; research on habit formation found that a single missed opportunity didn't materially set people back.^[2](#note-2)^ ## A session, start to finish *An illustration, not a reported family:* A father has twenty minutes at the kitchen counter while pasta water heats. **Specify (2 minutes).** On an index card: "Count how many items on a grocery list file. Input: a file with one item per line. Output: a number. Done when my five-line test file gives 5." **Predict (1 minute).** "I expect 5." **Build and Test (12 minutes).** He writes four lines that open the file and count lines. It prints 6. **Debug and Log (3 minutes).** Expected 5. Actual 6. Guess: there's an empty line at the end of the file. One change: open the file and look. Result: there is a blank last line. He updates the spec: "Blank lines don't count." Next session, he'll skip them. **Explain and File (2 minutes).** "I specified a list counter. I predicted 5. It did 6 because of a blank line. Next I'd change it to skip blank lines. Help I used: none." He saves to his learning folder and his backup drive, and the water boils. ## The try-it shape Every activity in this book appears in the same box, so you can read one at a glance: ### Out-of-home — OUT-02 Library Computer Session - **Time:** 45 minutes (desk) - **Materials:** your notebook; a USB drive or your own cloud storage; your library card - **Safety and privacy:** your own accounts only; save to your own drive; log out of everything and close the browser before you leave - **The fun:** a change of scene, and the quiet of a library table - **The skill:** running a full session on a public computer, and leaving it clean - **The crumb:** a file saved in two places **How it goes.** Library computers vary. Some let you install software; many let you use only a browser. Check what your library allows. Where you can't install anything, a website that runs short Python programs in the browser, such as Python Tutor, usually still works.^[3](#note-3)^ Then run one ordinary Hour there—spec, prediction, a little building, a log line. Save the file to your own drive and to one other place. Before you stand up, sign out of every account, close the browser, and check that nothing is left on the desktop. Write in your log that you did. It's a small rehearsal of a habit you'll teach your teen in Chapter 7: on a shared machine, you leave no trace. The fields are always in this order: **Time**, **Materials**, **Safety and privacy**, **The fun**, **The skill**, **The crumb**, then **How it goes**. The crumb is the small thing you keep—a page, a file, a card—so your records build themselves. ## The talk-to-yourself shape Each teaching chapter has one box for coaching yourself through a stuck moment. The questions always come in the same order. Here's the Hour's version: ### Talk to yourself (the Computing Hour) **Opening:** "Before I change anything, ask anyone, or ask a tool: what did I expect, what actually happened, and what's the one change I'll try?" **Follow-ups:** 1. **Prediction** — What did I write down before I ran it? 2. **Evidence** — What exactly did the screen or the trace show? 3. **Location** — Where is the first place reality and my expectation part ways? 4. **Change** — What's the one change I'll make, and what do I expect it to do? 5. **Revision** — Did my spec or my test need to change instead? **How to wait:** set a five-minute timer; trace by hand; read your spec aloud; stand up and come back. **What a stuck silence usually means:** the spec is fuzzy; you're tired; or the bug is in a line you're sure is fine—go there first. **Don't say / say instead:** Don't say "I'm just bad at this." Say instead "I haven't found it yet; here's what I know so far." ## Household safety basics Chapter 7 covers security at home in detail. Three basics belong here, because they apply from the very first session. - **Your accounts, your rules.** Use your own accounts for your own learning, and give each family member their own login on any shared computer. - **Practice only on your own systems.** Everything in this book that pokes at a network, a password, or a device is for systems you own, or have written permission to test. Never a workplace's, a school's, a library's, or a neighbor's. - **Keep family photos out.** Practice files use made-up or public data, and family photos stay out of AI tools and off shared computers. ## Screens on purpose Open the laptop for a job and close it when the job is done. Protect sleep and meals—yours and your household's. FAM-05 Screens on Purpose turns this into a short family plan; if you like a starting template, the American Academy of Pediatrics offers a Family Media Plan tool.^[4](#note-4)^ A good session often ends with the screen closed and the notebook still open. ## The AI box > **AI and your own learning** > > You hold your own accounts, so the rules here are the ones you choose—and the ones you'll ask your kids to keep. Try first. Write your prediction and your first attempt before you ask any tool (AI-01 Attempt, Then Ask). Then a tool can explain an error message, suggest a test you missed, or walk through a line you don't understand. > > What a tool makes is made by a tool. A suggested function becomes part of your work only after you can explain every line and it passes your tests. Write "Help I used: …" on the log every time, and keep an AI-04 Whose Work Is It? Card on every project you file. > > Tools are often fluent and wrong: they invent options and library names, use outdated ways of doing things, and cite sources that don't say what they claim. Run it, test it, and open the source. > > A careful study of high-school math students found that open access to a chatbot raised practice scores but lowered later unaided scores, while a version built to give hints protected learning.^[5](#note-5)^ That was teenagers and math, not adults and code—but the lesson about attempting first travels well. > > Keep private messages, family names, addresses, and photos of your children and family out of AI tools. At work, check your employer's rules before pasting any work code or data into a consumer tool. > > If you use Grok Bot, remember that all of your bots share one computer. Keep photos of your children and family off it, and keep your student's portfolio on a family drive. > > Terms change. Check the current age and privacy terms of any tool before your kids use it (Chapter 8). Every chapter's "Tools, including AI" section points back here and adds only what's different for that chapter. ## How much is enough The session lengths, the weekly budget, and the six-to-nine-month estimate in How to Use are planning estimates, not research findings. What the research does support is the shape: practice that asks you to retrieve and predict, spread across days rather than crammed into one long sitting, tends to stick better for most people than rereading.^[6](#note-6)^ That's why a twenty-minute Tuesday and a twenty-minute Thursday are worth more than they look. ## What to say, step by step Keep these on a card until they're automatic. - **Specify:** "Today I'm building ___ for ___. It takes ___ and gives back ___. It's done when ___." - **Predict:** "When I run it with ___, I expect ___." - **Debug and Log:** "Expected ___. Actual ___. My guess ___. One change ___. Result ___." - **Explain and File:** "I specified… I predicted… It did… Next I'd change… Help I used: …" - **With a child:** "What do you think it'll do?" → wait → "Show me on your page." → "What's one thing you could change?" Finish every session with LOG-01 The Learning Log Page: date, length, what you specified, predicted, and built, and the help you used. Five lines. Then close the laptop. \newpage # Chapter 1 ## Coming Back to Computing: Specs, Algorithms, and a Plan You'll Keep ![A one-page spec on a clipboard beside a flowchart sketch, a few index cards and a pencil — still life, no people, no logos, no readable text.](art/ch01-opener.jpg){width=100%} ## Why this matters There's a popular story about programming. It says programming belongs to the young and the gifted, that you either "get it" quickly or you never will, and that the people who are good at it were somehow born that way. It's a common story, and it's easy to believe if your last memory of a programming class is a screen full of errors and a classmate who seemed to understand everything. The better picture is plainer and much more encouraging. Researchers who reviewed decades of work on how beginners learn to program found that what separates the novices who make progress from the ones who stall is mostly *strategy*: planning before typing, tracing what the code will do, testing it, and fixing one thing at a time.^[1](#note-1)^ Those are habits, and habits can be learned at any age. **The Computing Hour** you just read is nothing more than those strategies, put in order. Adults learn this in every decade of life. In one large survey of more than five hundred people aged 60 to 85 who were learning to program, the most common reason given was making up for chances they'd missed when young; the most common frustrations were finding the time and having nobody to learn with.^[7](#note-7)^ (The respondents were a self-selected and highly educated group, so treat this as a picture of some learners, not all.) Missed chances, not enough time, no one to learn with: if any of that sounds familiar, this chapter is built for it. Here's the other thing the popular story gets wrong. It treats typing code as the hard part. In practice, the hard part is saying exactly what you want. A computer does what you tell it, with no common sense and no mercy, and most programs that "don't work" are doing precisely what they were told. So this chapter starts on paper, with the skill that makes every later chapter easier: writing a short, clear spec, and turning it into exact steps. By the end of the chapter you'll have a dated baseline page, a why card, a fixed cue for your sessions, a one-page spec for a first small project, and a trace table you've checked by hand. You'll also have a plan for the next month that fits the life you actually have. ## Understand it yourself ### The plain picture An algorithm is a recipe written for a cook who does exactly what it says. Not what you meant—what it *says*. Tell this cook "add salt" and they'll stand there, because you didn't say how much, or when, or which bowl. Tell them "stir until smooth" and they might stir forever, because they don't know what smooth looks like. Every ambiguity in your recipe becomes a bug. A spec comes before the recipe. It's a short written description of what a program must do, with examples and a line saying what "done" means. If the algorithm is the recipe, the spec is the note on the fridge that says: "Dinner for six, one vegetarian, on the table by 6:30, nothing with nuts." ### The precise picture An algorithm is a finite list of unambiguous steps that takes some input and produces some output. Each word in that definition is doing work. *Finite*: it must stop. *Unambiguous*: each step has exactly one meaning. *Input and output*: it starts from something and gives back something. A good spec has six parts, and SPEC-01 The One-Page Spec uses all of them: 1. **Purpose**—one sentence on what it's for. 2. **User**—who will use it (often you). 3. **Inputs**—what goes in. 4. **Outputs**—what comes out. 5. **Rules**—what it must always or never do. 6. **Done line**—how you'll know it's finished, written so you can check it. The done line is the part people skip, and it's the part that saves you. "Make it work" is not a done line. "Given four people and six chores, it prints six lines, each with one chore and one name, and nobody gets three chores in a row" is a done line. You can check it. Examples belong in the spec too. SPEC-02 Examples Before Code asks you to write pairs—this input, that expected output—including edge cases. An edge case is an input at the boundary, or an odd one a careless user might type: an empty list, one person instead of four, a zero, a word where a number should be. Writing the edge cases before you write any code is the single cheapest way to avoid a whole category of bugs. ### A name for all this, once Educators have a name for the habits underneath all of this: **computational thinking**—breaking a problem into parts, spotting patterns, leaving out what doesn't matter, and writing steps a machine can follow. That's the only time this book will use the phrase. From here on, we'll just name the habits. ### Searching and sorting as counting work Two ideas from computer science explain a surprising amount of the world, and you can learn both with a deck of cards. **Searching.** Suppose you're looking for the seven of hearts in a shuffled pile. The only reliable way is to look at each card in turn until you find it. That's *linear search*. If the pile has 52 cards, the worst case is 52 looks. Double the pile, double the looks. Now suppose the pile is sorted, lowest to highest. You can open it in the middle, see whether you've gone too far or not far enough, and throw away half the pile with one look. Then do it again with the half that's left. That's *binary search*. With 52 sorted cards, you need at most six looks. Double the pile, and you need just one more look. ALG-01 Two Ways to Search has you count this by hand, and the counts are memorable. The catch: binary search only works on a sorted pile. Using it on a shuffled one is a classic wrong answer, and it fails quietly—it just doesn't find things that are there. **Sorting.** To sort a pile by hand, one way is to look through the whole pile for the smallest card, set it aside, then look through what's left for the next smallest, and so on. That's *selection sort*. It's easy to understand and slow on big piles, because you keep re-scanning. Another way is to split the pile in half, and halves into halves, until every pile has one card, then merge pairs of piles back together in order. That's *merge sort*. It feels fussier with real cards, but it does far fewer comparisons on big piles. ALG-02 Sort by Hand, Count the Work has you tally the comparisons both ways. You don't need to memorize either algorithm. What matters is the idea underneath: different correct algorithms can do wildly different amounts of work, and you can count that work on paper before you ever touch a computer. ### Trace tables A trace table is how you run a program in your head without fooling yourself. You make one column for each variable and one row for each step, and you fill in the values as the program would. Here's a three-line loop: ```python total = 0 for n in [4, 7, 2]: total = total + n print(total) ``` | Step | n | total | |---|---|---| | start | — | 0 | | loop 1 | 4 | 4 | | loop 2 | 7 | 11 | | loop 3 | 2 | 13 | | print | — | 13 | The program prints `13`. The trace table caught nothing here, but it's in the habit of catching things that you won't see by squinting. ALG-03 Pseudocode to Trace Table is the card; you'll use trace tables in every chapter after this one. ### Wrong answers you should be able to hear These come up in your own work and in your child's, and each has a gentle reply. - **A spec with no done line.** "It should pick chores fairly." Say: "What exactly should happen when it's done? How would you check it?" - **"Make it work" as a requirement.** It means the spec isn't written yet. Say: "Work how? Give me one example: this goes in, that comes out." - **A binary search on an unsorted pile.** It fails without complaint. Say: "What has to be true about the pile before we can split it?" - **A trace table that skips the loop's last pass.** This is the most common tracing slip there is. Say: "How many items are in the list? How many rows do we have?" - **"It should just work."** Usually there's no spec at all. Say: "Let's write down what 'work' means first." ### A five-minute warm-up Write the steps for brushing your teeth, as if for a robot that has never seen a toothbrush. Then circle every ambiguous word. "Some" toothpaste. "Brush" for a while. "Rinse." Most people circle six or seven words in a ten-step list. Each circle is a spec bug you've just learned to see. ## How to run it this week This week's three sessions use the Hour's steps from the start. You won't open a code editor until Chapter 2—this is all paper—but you'll Specify, Predict, Build and Test, Debug and Log, and Explain and File just the same. The "build" is a page instead of a program. ### Session 1 (desk, about 30 minutes): Baseline and why ### In-home — START-01 The Baseline Page - **Time:** 30 minutes (desk) - **Materials:** your notebook, a pencil, a timer - **Safety and privacy:** your own notebook; nothing online - **The fun:** finding out you know more than you thought, or getting to start completely fresh - **The skill:** writing, from memory and with no help, what you can already read, trace, and build - **The crumb:** a dated baseline page **How it goes.** At the top of a fresh page, write today's date and "Baseline." Then answer three questions in plain words, with no looking anything up: What can I read? (A recipe? A spreadsheet formula? A few lines of any programming language?) What can I trace? (Could I say what a short loop does?) What can I build? (Anything—a spreadsheet that totals a column counts.) Then copy the three-line loop from the trace table section without looking at the answer, and predict what it prints. Write the prediction down. Check it against this chapter. The page is your starting line, and in a few months it will be the most encouraging page in your notebook. Then do START-02 Why Card: on an index card, one sentence each for why you're learning, for whom, and what you'll build first. "To help my daughter with Python, and for me, because I've always wondered. First: a chore picker for our house." Tape it inside the notebook's front cover. **Self-talk for Specify, this session:** "What exactly will be on this page when I'm done, and how will I know I'm finished?" The done line here is easy: a dated page with three answers and one checked prediction. ### Session 2 (micro, about 15 minutes): Cue and kit START-03 Cue and Kit asks you to choose a fixed cue—an event already in your day that will mean "session now." After the morning coffee. After school drop-off. After the dishes on Tuesday and Thursday. A cue tied to something that already happens is far sturdier than a time on a calendar. Then set out the kit: notebook, pencil, index cards, and (once you have it) one saved file. Leave the kit where you'll see it at the cue. Habits form over weeks to months, not days. In one well-known study of everyday habits, the median time for a new behavior to become automatic was about 66 days, with a wide range—and one missed day didn't materially set anyone back.^[2](#note-2)^ That's a useful study, not a promise that every reader will see the same timeline. The practical message: expect it to take a while, and don't treat a missed session as a broken streak. Finish with PLAN-01 The Week on One Card for next week. ### Session 3 (desk, about 40 minutes): Your first spec Use SPEC-01 The One-Page Spec for a small program you'd actually like to have. The worked session below shows one start to finish. ### Stopping when the timer ends Stop when the timer ends, even mid-thought. Write one line in your log saying exactly where you stopped—"Halfway through the examples table; next is the empty-list case"—and close the notebook. Stopping on time is what makes it possible to start again on Thursday. Unfinished work with a clear next step is a gift to your future self. ### Worked session: a chore-rotation picker *An illustration, not a reported family:* A mother of three has forty minutes at the dining table on a Wednesday evening. **Specify (8 minutes).** She writes SPEC-01 for a chore-rotation picker: > **Purpose:** Each week, assign each chore to one person, rotating so nobody gets the same chore two weeks running. > **User:** Me, every Sunday night. > **Inputs:** a list of chores, a list of people, the week number. > **Outputs:** one line per chore: the chore and who has it. > **Rules:** every chore gets exactly one person; the assignments shift by one each week. > **Done line:** for three chores, two people, and week 1, it prints three lines, and week 2 gives each chore a different person than week 1 did. Then she adds SPEC-02 examples, including the edge cases: | Chores | People | Week | Expected | |---|---|---|---| | dishes, trash, laundry | A, B | 1 | dishes→B, trash→A, laundry→B | | dishes, trash, laundry | A, B | 2 | dishes→A, trash→B, laundry→A | | (none) | A, B | 1 | nothing printed | | dishes | (none) | 1 | ??? | She stops at the last row. What *should* happen with no people? She doesn't know, and that's the point: the spec found a question before any code existed. **Predict (2 minutes).** She sketches the steps in plain words—"for each chore, count along the people list, starting further along each week, wrapping around at the end"—and predicts the first example will match the table. **Build and Test (20 minutes).** Her "build" is the algorithm, in pseudocode, and a trace table for the first example. You won't write Python until Chapter 2, but here is what her plan becomes in a few weeks, so you can see where it's going: ```python def pick(chores, people, week): for i in range(len(chores)): person = people[(i + week) % len(people)] print(chores[i], "->", person) pick(["dishes", "trash", "laundry"], ["A", "B"], 1) # dishes -> B # trash -> A # laundry -> B ``` The `%` sign means "the remainder after dividing," which is how the counting wraps around the list. Her hand trace of week 1 matched the expected row exactly. **Debug and Log (6 minutes).** She traces the empty-people row. Dividing by the length of an empty list means dividing by zero. On paper, the step can't be done at all. Her log: > **Expected:** something sensible when there are no people. > **Actual (on paper):** the step "count along the people list" has nothing to count; it divides by zero. > **Guess:** the spec never said what to do with no people. > **One change:** add a rule to the spec. > **Result:** new rule: "If there are no people, print 'Add someone first' and stop." (When she ran the Python version weeks later, Python agreed: it stopped with `ZeroDivisionError: integer modulo by zero`. The paper trace had found the same bug, a day earlier, with a pencil.) **Explain and File (4 minutes).** "I specified a chore picker for two people and three chores. I predicted week 1 would match my table, and on paper it does. The empty-people case divides by zero. Next I'd change the spec to say 'Add someone first.' Help I used: none." She files the spec and the trace in her notebook and photographs both pages to her backup folder. ## Practice that actually builds it ### Blocked, then mixed Start with **blocked practice**: three specs in a row, one each session or all in one deep session. Pick three small, real things—a tip splitter, a reading log that totals pages, a grocery list that flags anything you bought last week. Write all six parts and at least four examples each, including two edge cases. By the third, you'll write the done line first without being told. Then switch to **mixed practice**: in each session, do one spec, one trace, and one sort or search by hand. Mixing feels harder, and that's partly why it works: you have to recognize which tool the problem needs, which is the real skill. ### Diagnose this Here's a spec someone handed in. What's missing? > **Purpose:** A program for tracking my reading. > **User:** me. > **Inputs:** books. > **Outputs:** my reading stats. > **Rules:** should be easy to use. > **Done line:** when it works. Nearly everything. "Books" isn't an input you can type—a title? pages? a date finished? "Reading stats" could mean anything. "Easy to use" can't be checked. And "when it works" is the classic non-done line. A repaired version: "Inputs: title, pages, and date finished for each book. Output: total pages this month and the number of books. Done when three sample books from the examples table give 812 pages and 3 books." Now you could build it—and know when to stop. ### In-home — SPEC-03 The Literal Reader - **Time:** 15 minutes (micro) - **Materials:** bread, a spread, a plate, a butter knife; a written list of steps; two colored pens - **Safety and privacy:** a butter knife only; at home, with people who've agreed to play - **The fun:** watching a grown adult (or a delighted child) refuse to open the bread bag because you didn't say to - **The skill:** repairing every ambiguity in written steps - **The crumb:** marked-up steps in two colors **How it goes.** Write the steps for making a jam sandwich. Hand them to a partner or your child, who follows them *exactly* as written—and no more. "Put jam on the bread" may produce a jar set on top of a closed loaf. Every wrong turn is a spec bug. Mark each one in the first color; write the repair in the second. Then run it again. Most people need three rounds. With a young child as the literal reader, expect laughing; with a teen, expect a certain rigorous joy in being unhelpful. Either way, you'll never write "add salt" without a quantity again. ### Out-of-home — OUT-01 Algorithms in Public - **Time:** 20 minutes (micro) - **Materials:** your notebook, a pencil - **Safety and privacy:** observe only; no photos of people or screens; don't hold up a line - **The fun:** seeing the rules behind ordinary machines - **The skill:** writing a spec from observation - **The crumb:** a spec page for a machine you've watched **How it goes.** Pick a self-checkout, an elevator, or a crosswalk signal. Watch it work for a few minutes, then write its spec as if you were its programmer. What are the inputs (a scanned item, a weight on the bagging area, a button press)? What are the outputs? What are the rules? The best part is the edge cases: what happens when you put an item down without scanning it, or press the elevator button for the floor you're already on, or press the crosswalk button twice? Write your prediction, then—if it's safe and polite—watch for the answer. You'll start noticing that every machine you use was once a spec somebody wrote, and that some of them were missing a row. ### More from the bank for this chapter - **ALG-04 Recipe or Algorithm?** (micro): rewrite a household routine—laundry is ideal—as precise steps with one loop ("repeat until the basket is empty") and one decision ("if it's wool, then…"). - **SPEC-05 Spec Diff** (micro): after any small project, compare what the spec said with what you actually built, and write a two-line change note. It's the habit that keeps specs honest. - **PLAN-03 Scope It Down** (micro): take a project idea that's too big ("an app for the whole family's schedule") and cut it to a version you could finish in two weeks of sessions ("print this week's pickups from a list I type in"). ### Talk to yourself (this chapter) **Opening:** "What exactly should happen when this is done, and how small can I make it?" **Follow-ups:** 1. **Prediction** — What did I expect this step, or this example, to produce? 2. **Evidence** — What does my trace table actually show, row by row? 3. **Location** — Which row, or which word in my spec, is the first place it goes wrong? 4. **Change** — What's the one rule or example I'll add, and what will it fix? 5. **Revision** — Is the problem in my steps, or did my spec never say what I wanted? **How to wait:** set a five-minute timer; read your spec aloud as if to a stranger; trace one more row by hand. **What a stuck silence usually means:** the done line is missing. Go write it before anything else. **Don't say / say instead:** Don't say "I'll figure it out as I go." Say instead "Done means ___; I'll check it by ___." ## Coaching your kids at every age You don't need to be ahead of your child to coach this chapter. You need the habits you just practiced: a done line, a prediction, a trace. Here's how each translates. ### Ages 5–10 **The move:** be the literal robot. COACH-01 Literal Robot for a Five-Year-Old turns your child into the programmer and you into a machine that does exactly what it's told. Put a stuffed animal across the room. Your child gives you steps—"walk forward," "turn"—and you do *exactly* that. Walk forward until you bump into the couch, because they didn't say how many steps. Turn in a full circle, because they didn't say which way or how far. **Exact words:** "What will I do if you tell me that?" and "How many steps?" Then do what they said, cheerfully, even when it's wrong. **One thing to avoid:** fixing their instructions by doing what they meant. The whole lesson is in the gap between what they said and what they meant; if you quietly close the gap, the lesson vanishes. *Computing for Little Thinkers*, Chapter 2, "Steps and Algorithms," has a full set of these games if you want more. ### Ages 11–14 **The move:** ask for a written prediction before anything runs (COACH-02 Ask for the Prediction). At this age, kids often want to press Run and see. That's fine—after the prediction. One line on their page: "I predict it will print…" **Exact words:** "What do you think it'll do? Write it down first." And when it surprises them: "Ooh. Where did your guess and the computer part ways?" **One thing to avoid:** treating a wrong prediction as a mistake. A wrong prediction is the most useful event of the session. If you say "oops," they'll stop writing predictions they're unsure of, which are exactly the ones that teach. ### Ages 15–18 **The move:** read their spec for a done line. Teens can build real things, and they often skip straight to building. Your job is the question that makes a project finishable. **Exact words:** "How will you know it's finished?" If the answer is "when it works," ask for one example: "This goes in, what comes out?" **One thing to avoid:** writing the done line for them. Ask, wait, and let them write it. If they ask you what *you* think done looks like, that's a great conversation—and they still hold the pencil. ### At every age: "I don't know yet" COACH-09 What I Don't Know Yet is the move that makes all the others possible. When your child asks something you can't answer, say "I don't know—let's find out," and then show them how you look. Children learn far more from watching a calm adult search than from an adult who always has the answer. ## If it isn't clicking **Your specs keep ballooning.** Every spec turns into a plan for the whole family's digital life. Use PLAN-03 Scope It Down: write the big version, then cross out everything that isn't needed for the first useful version. If you can't finish it in two weeks of sessions, cut again. **Your traces skip steps.** You trace four rows when the loop has five, or you jump to the answer. Slow down to one row per line of code, even when it feels silly. Put your finger on the line you're tracing. The skipped row is almost always the last pass through a loop. **Your algorithms are vague in the middle.** The first step and the last step are clear, and everything between them says something like "sort out the rest." That middle is where the program lives. Take the vague line and ask of it what a literal reader would ask: which item first? compared with what? what happens when two are equal? when do I stop? Write each answer as its own numbered step. If a step still needs judgment, split it again. You're done when a stranger could follow the steps with a pencil and get the same answer you would, without asking you a single question. **The habit won't stick.** Three weeks in, sessions keep not happening. Shrink every session to micro, and move the cue (START-03). A cue that depends on a quiet evening will fail in a busy week; a cue tied to the morning coffee will usually survive. Also check your why card—if it no longer sounds like you, rewrite it. **When to get a person.** First run the rescue order from **The Computing Hour**: reread your spec, wait, hint, a worked example in a scratch file, then back to your own file. If you've logged two sessions stuck on the same thing, ask a human. OUT-03 Find Your People is the card for it: visit a library coding group, a meetup, or a community-college open house. Learning with someone else helps; in programming courses, working in pairs has shown positive effects on learning across many studies.^[8](#note-8)^ That evidence comes from classroom courses, not home study, but a friend at the next chair seems to work the same way for many adults. And having nobody to learn with is one of the most common frustrations adults report—so this one's worth an evening. ### Out-of-home — OUT-03 Find Your People - **Time:** 45 minutes (desk) - **Materials:** your notebook; one question you'd like answered - **Safety and privacy:** a public meeting; share only your first name if you prefer - **The fun:** meeting people who are also figuring it out - **The skill:** finding a place to learn with others - **The crumb:** notes and the date of the next meeting **How it goes.** Look for a coding group at your public library, a local meetup for beginners, or an open house at a community college's continuing-education program—check what's near you. Go once, with one question written down. You don't have to say anything; listening counts. Before you leave, write the date of the next meeting in your notebook. Most adults say the second visit is much easier than the first. ## Tools, including AI This chapter's tools are a pencil, index cards, a deck of playing cards, and a notebook. That's on purpose. Specs and traces are thinking work, and paper keeps the thinking yours. For AI tools, everything in the AI box in **The Computing Hour** applies. One thing is specific to this chapter: write your first spec yourself, without asking a tool to write it for you. A tool can produce a tidy-looking spec in seconds, but it can't know what you actually want, and the act of discovering what you want—like the mother who found she didn't know what should happen with no people—*is* the skill. Once your spec is written, it's fine to ask a tool "What edge cases might I be missing?" and then decide for yourself which ones matter. Log it. You may hear claims that learning to program makes people better at thinking in general. The evidence for that kind of broad transfer is modest: skills near programming tend to benefit more than distant ones.^[9](#note-9)^ This is a useful study, not a promise that every reader will see the same result. Learn programming for what it is. That's plenty. ## What "done enough" looks like You're ready to move on to Chapter 2 when you have: - [ ] a dated baseline page (START-01) - [ ] a why card taped inside your notebook (START-02) - [ ] a cue and a kit you've used at least three times (START-03) - [ ] one SPEC-01 spec with all six parts and a checkable done line, plus a SPEC-02 examples table with at least two edge cases - [ ] a correct trace table for a short loop, including the last pass (ALG-03) - [ ] step counts for linear and binary search on at least two pile sizes (ALG-01) - [ ] AS-01 Cold Trace once: trace a short program you haven't seen, unaided, and predict its output - [ ] AS-02 Debug on the Spot once: find a planted mistake in a short set of steps while explaining aloud (a partner can plant it) - [ ] AS-04 Explain Your Code once: walk a partner, or a voice recorder, through your spec and trace line by line Place yourself by these skills, not by how long you've been at it. If you can already do all of them, move on today. If two weeks in you can do most of them, that's done enough; the rest will come with practice in Chapter 2. \newpage # Chapter 2 ## Python as a Working Tool ![An open laptop whose screen shows rows of indented colored bars, beside a printed data file and a mug, near a window — still life, no people, no logos, no readable text.](art/ch02-opener.jpg){width=100%} ## Why this matters A program is a tool you can keep. Write a recipe scaler once and it scales every recipe for the rest of your life. Write a little script that totals the miles in a log and it totals next year's log too. That's the grown-up reason to learn Python: not to become a different kind of person, but to own a few small tools that do real jobs in your house, and to understand the ones your kids are building. Python is a programming language—a precise way of writing steps a computer can follow. This book uses Python because it reads close to plain English, because its error messages are more helpful than most, and because it's the typed language the later books in this series use for children. When your twelve-year-old moves from blocks to text, it will very likely be Python on the screen, and you'll recognize it. This isn't a claim that Python is the best language; it's a good first one, and the habits you build here carry to any other. The chapter teaches a small set of ideas well: variables and input, functions that hand back a value, reading and writing files, lists and dictionaries, finding answers in the official documentation, and one small class designed on index cards first. By the end you'll have a program that reads a file, does something useful with it, and writes a report—and you'll be able to explain every line. Beginners learn programming best from guided examples, not from being dropped in front of a blank screen and told to discover it.^[10](#note-10)^ So this chapter works in a particular shape, borrowed from a well-tested approach to teaching programming in schools: **predict** what a short example will do, **run** it, **investigate** how it works, **modify** one thing, and then **make** something of your own.^[11](#note-11)^ You'll see that shape in every session. ## Understand it yourself ### The plain picture A **variable** is a labeled jar. `cups = 2` means "put 2 in a jar labeled *cups*." Later you can look in the jar, or empty it and put something else in. A **function** is a recipe card you can call by name. You write the card once—"to scale a recipe, take the amount, multiply by the new servings, divide by the old servings"—and after that you just say "scale" with the numbers, and the card does the work and hands you the answer. A **list** is a shopping list: things in order, numbered from the top. A **dictionary** is a set of labeled drawers: you find things by their label, not their position. A **file** is a page the program can read from or write on, which stays there after the program stops. ### The precise picture A variable is a name bound to a value. Every value has a **type**—what kind of value it is: a whole number (`int`), a decimal number (`float`), text (`str`, short for "string"), a list, and so on. Types matter, because the same symbol does different things to different types. `3 * 2` is `6`. `"3" * 2` is `"33"`—text repeated twice. `input()` asks the person at the keyboard to type something and gives it back—always as text, even if they type a number. This is the single most common surprise for adult beginners, and the worked session below is built around it. A function is defined with `def`, takes **parameters** (the names for its inputs), and **returns** a value with `return`. The **return value** is what it hands back to whoever called it. `print()` is different: it shows something on the screen and hands back nothing useful. A function that prints its answer instead of returning it looks fine on screen and is useless to the rest of your program. A **docstring** is a short description in quotes on the first line inside a function, saying what it does. It's a spec, built into the code. Files are opened with `with open(...) as f:`. The `with` means Python closes the file for you when the indented block ends, even if something goes wrong. Lists are accessed by position, starting at zero: in `["milk", "eggs"]`, `"milk"` is item 0. Dictionaries are accessed by key: in `{"milk": 3}`, the key `"milk"` gives you `3`. A **class** is a blueprint; an **object** is one thing built from it. You'll meet one small class near the end of the chapter, on index cards first. ### Wrong answers you should be able to hear - **`input()` treated as a number.** "I typed 2, why did it print 222?" Say: "What type does `input()` give back? Let's print it." - **A function that prints instead of returns.** The answer appears, but the next line gets `None`. Say: "What does this function hand back? Not show—hand back." - **A dictionary used where order matters to the reader.** A shopping list stored as a dictionary loses the meaning of "first" and "last" for whoever reads the code, even if the program happens to keep it. Say: "Do you need to find things by name, or keep them in order?" - **Reading a file without closing it.** It often works, until it doesn't. Say: "Let's use `with`, so Python closes it for us." - **A class with data but no actions.** A "Book" class that only stores a title is just a labeled box. Say: "What does a book *do* in your program? Check out? Renew?" ### A five-minute warm-up Predict what each of these prints, on paper, before reading on. ```python print(3 * 2) print("3" * 2) print(10 / 4) print(10 // 4) ``` They print `6`, `33`, `2.5`, and `2`. The second surprises most people (text repeated), and the fourth surprises nearly everyone: `//` divides and throws away the remainder. If you got all four, wonderful. If you missed one, even better—you've just found a corner of your picture to repair, and that's exactly what PY-01 Predict the Output is for. ## How to run it this week ### Session 1 (desk, about 40 minutes): Set up once ### In-home — START-04 Set Up a Clean Workspace - **Time:** 40 minutes (desk) - **Materials:** a computer you're allowed to install software on; your notebook - **Safety and privacy:** download only from the official site for the editor or Python itself; practice folder only - **The fun:** the first time a computer says hello because you told it to - **The skill:** installing a Python editor, making one learning folder, and saving a first file in two places - **The crumb:** a folder with a hello file and a backup copy **How it goes.** Install a beginner-friendly Python editor. Thonny is a good choice: it comes with Python built in, and its debugger lets you step through a program one line at a time.^[12](#note-12)^ Any plain editor plus Python 3 from the official site works too; check the current version of whichever you choose rather than trusting a screenshot from an old tutorial. Then make one folder called something like `learning`, and inside it a file called `hello.py` with one line: `print("Hello from my kitchen table")`. Before you run it, write your prediction. Run it. Then copy the folder to a second place—a USB drive or your own cloud storage. Every file in this book gets saved in two places, starting tonight. ### Session 2 (micro, about 15 minutes): Predict the Output PY-01 Predict the Output: take the warm-up above, or any three short lines from this chapter, write your predictions, run them, and write the result next to each prediction. Log any surprise in the Debug Log. Fifteen minutes, three lines of code, and you've practiced the most important habit in the book. ### Session 3 (desk, about 35 minutes): A calculator you need PY-02 Variables, Input, and a Calculator You Need. The worked session below is one version of it; your version should solve a calculation that turns up in your own house. A mileage log. A tip splitter. Paint coverage for a room. Pick one you'll actually use. **Self-talk for Predict, this chapter:** "What will this print, line by line, before I run it?" Say each line aloud with its predicted output. If you can't predict a line, that's the line to investigate. ### Stopping when the timer ends Stop mid-program if the timer says so. Write one comment at the top of the file—`# NEXT: handle the case where someone types a word`—and save it in two places. Tomorrow-you will open the file and know exactly where to start. ### Worked session: the recipe scaler *An illustration, not a reported family:* A father who bakes on weekends has thirty-five minutes on a Thursday night. **Specify (5 minutes).** On an index card: > Recipe scaler. Input: cups of an ingredient for 4 servings; the servings I want. Output: cups for the new servings. Done when 2 cups for 4 gives 3 cups for 6, and 1.5 cups for 4 gives 0.75 for 2. **Predict (2 minutes).** He starts small: just ask for the cups and multiply, to see the input working. "If I type 2 and multiply by 3, I'll see 6." **Build and Test (15 minutes).** ```python cups = input("Cups for 4 servings: ") # he types 2 print(cups * 3) ``` The screen shows `222`. **Debug and Log (8 minutes).** He doesn't change anything yet. He writes: > **Expected:** 6 > **Actual:** 222 > **Guess:** it's treating 2 as text and repeating it, like `"3" * 2` in the warm-up. > **One change:** turn the input into a number with `float()`. > **Result:** see below. ```python cups = input("Cups for 4 servings: ") # types 2 cups = float(cups) print(cups * 6 / 4) # prints 3.0 ``` It prints `3.0`. That's 3 cups—his spec said 3, and `3.0` is Python's way of writing a decimal 3. He updates the spec: "3.0 is fine." Then he turns the calculation into a function so he can reuse it: ```python def scale(amount, old_servings, new_servings): """Return amount scaled from old_servings to new_servings.""" return amount * new_servings / old_servings print(scale(2, 4, 6)) # 3.0 print(scale(1.5, 4, 2)) # 0.75 ``` Both examples from his done line pass. **Explain and File (5 minutes).** "I specified a recipe scaler. I predicted 6 and got 222, because `input()` gives text. I changed it with `float()` and got 3.0, then wrote a `scale` function and both examples pass. Next I'd change it to ask for the servings instead of typing them into the code. Help I used: none." He saves it in his learning folder and his backup, and he can explain every line, including the docstring. ### Modify: when someone types a word PRIMM's fourth step is *modify*, and the recipe scaler offers a perfect one. Run it again and, when it asks for cups, type `two` instead of `2`. Predict first. Most people guess "it'll print something strange." Instead, the program stops, and the last line of the red text says: ``` ValueError: could not convert string to float: 'two' ``` Read it slowly, because it's being helpful. *ValueError*: the type was right (text) but the value was one Python couldn't use. *Could not convert string to float*: it tried to turn text into a decimal number. *'two'*: here's the exact text it choked on. (Stray spaces, by the way, are fine: `float(" 2 ")` quietly gives `2.0`. It's letters that stop it.) You don't have to fix this today. A good move for now is to add a line to your spec—"If someone types a word, the program may stop; that's acceptable for version one"—and a note for later. Chapter 3 shows how to test for it, and how to decide, in the spec, what *should* happen. Deciding is the part that's yours. Python can tell you what went wrong; only you can say what you wanted instead. That's the rhythm of the whole chapter in small: predict, run, investigate the surprise, change one thing, and write down what you learned. None of it requires you to know more Python than you did ten minutes ago. It requires you to look closely, which you already know how to do. ## Practice that actually builds it ### Blocked: three small functions Write three functions in a row, each with a docstring and a return value, each tested with two examples you write *before* the code (PY-03 Functions With Return Values): 1. `tip(bill, percent)` returns the tip. 2. `split(total, people)` returns each person's share. 3. `total_with_tip(bill, percent, people)` *calls the first two* and returns each person's share including tip. The third is the real lesson: a function calling another function. Predict what `total_with_tip(60, 20, 3)` returns before you run it. (The tip is `12.0`, the total is `72.0`, and each share is `24.0`. Division in Python always gives a decimal number, which is why the `.0` appears.) ### Diagnose this: print instead of return Here's a function someone wrote. Predict the two lines of output before reading on. ```python def total(prices): s = 0 for p in prices: s = s + p print(s) result = total([2, 3, 5]) print(result) ``` It prints `10` and then `None`. The first line comes from the `print` inside the function. The second shows what the function handed back: nothing, which Python calls `None`. The fix is one word: change `print(s)` to `return s`. After the fix, the program prints one line, `10`, and `result` holds a number the rest of your program can use. ### Read a file, count something PY-04 Read a File, Count Something is the first program in this book that feels like a real tool. Make a text file called `list.txt` in your learning folder with one grocery item per line: ``` milk eggs milk bread milk ``` Then this program counts how many times each item appears and writes a small report: ```python counts = {} with open("list.txt") as f: for line in f: item = line.strip() counts[item] = counts.get(item, 0) + 1 print(counts) with open("report.txt", "w") as out: for item in sorted(counts): out.write(item + ": " + str(counts[item]) + "\n") ``` The screen shows `{'milk': 3, 'eggs': 1, 'bread': 1}`, and a new file, `report.txt`, appears in your folder with three lines: `bread: 1`, `eggs: 1`, `milk: 3`. Before you run it, predict both. Then investigate: what does `strip()` do? (It removes the invisible end-of-line character and any stray spaces; without it, `"milk"` and `"milk "` would be different items.) What does `counts.get(item, 0)` do? (It looks in the drawer labeled `item`, and gives 0 if there's no such drawer yet.) Then modify one thing—count only items that appear more than once—and predict again. ### Mixed: list or dictionary? PY-05 Lists, Dictionaries, and When is a micro session on paper. For each job below, choose a list or a dictionary and write one sentence saying why: - the order you'll visit stores on Saturday (a list—order matters) - how many of each item you need (a dictionary—you look things up by name) - this week's chore rota from Chapter 1 (try it both ways and decide) - the books each child has checked out (a dictionary whose values are lists) There's no single right answer for the third; the reason is the skill. ### Reading the official documentation PY-06 Use a Library, Read Its Docs. Python comes with a large standard library—ready-made modules for dates, files, random numbers, and much more. The official documentation at docs.python.org is the authority, and it's written for people who already know a little, which makes it intimidating at first. The trick: read the examples first, and only then the explanation around them. Try it with dates. Suppose you want to know the due date of a library book three weeks from a given day. Search the documentation for `timedelta`, find the example, and adapt it: ```python import datetime borrowed = datetime.date(2026, 10, 13) due = borrowed + datetime.timedelta(days=21) print(due) # 2026-11-03 ``` Predict the date by counting on a calendar first. Then, in your notebook, copy the one line from the documentation that answered your question. That docs note is the crumb, and it's also a habit you'll ask your teen to show you. ### In-home — PY-07 A Small Class on Index Cards - **Time:** 20 minutes (micro) - **Materials:** three index cards, a pencil - **Safety and privacy:** made-up titles only - **The fun:** designing a tiny piece of software without touching a keyboard - **The skill:** designing one class: what it knows and what it does - **The crumb:** a card set **How it goes.** On the first card, write the class's name: *LibraryBook*. On the second, what every library book knows: a title, a due date, how many times it's been renewed. On the third, what it can do: renew (push the due date later and add one to the renewal count). Now pretend to be a book. Have someone tell you "renew by 7 days," and update your cards. Only then write it in Python: ```python class LibraryBook: def __init__(self, title, due): self.title = title self.due = due self.renewals = 0 def renew(self, days): self.due = self.due + days self.renewals = self.renewals + 1 book = LibraryBook("Gardening Basics", 14) book.renew(7) print(book.title, book.due, book.renewals) ``` Here, the due date is just "day 14" to keep it simple. Predict the output before you run it: `Gardening Basics 21 1`. The class is the blueprint; `book` is one object built from it. `__init__` is the part that runs when a new book is made, and `self` means "this particular book." ### Out-of-home — OUT-02 Library Computer Session - **Time:** 45 minutes (desk) - **Materials:** your notebook; your files on a USB drive or in your own cloud storage - **Safety and privacy:** your own accounts; save to your own drive; sign out and close the browser before you leave - **The fun:** a change of scene for a stuck project - **The skill:** running a full session on a public computer and leaving it clean - **The crumb:** a file saved in two places **How it goes.** You met this card in **The Computing Hour**; this time, take this chapter's file-counting program to a library session. Check what your library's computers allow; if you can't install anything, a website that runs Python in the browser, such as Python Tutor, may work for a short program (a file-reading program may need its sample lines pasted in as a list instead). Run one Hour—spec, prediction, a small change, a log line. Save to your own drive, then sign out of everything, close the browser, and log it. A change of chair is surprisingly good for a stuck bug. ### Talk to yourself (this chapter) **Opening:** "What will this print, line by line, before I run it?" **Follow-ups:** 1. **Prediction** — What did I write down for each line? 2. **Evidence** — What exactly did the screen show? Copy it, red text and all. 3. **Location** — Which line is the first one whose output surprised me? 4. **Change** — What's the one change I'll make—often, printing the value and its type—and what do I expect it to show? 5. **Revision** — Was my spec wrong about what the output should look like? **How to wait:** set a five-minute timer; trace the code by hand in a trace table, one row per line; read the last line of the error aloud. **What a stuck silence usually means:** a value's type isn't what you think. Text that looks like a number is still text. **Don't say / say instead:** Don't say "Python is being weird." Say instead "Let me print the value and its type." That last move is worth seeing once: ```python x = "5" print(x + "5") # 55 print(type(x)) # ``` `55`, because `x` is text, and adding text joins it. `type()` tells you so. ## Coaching your kids at every age ### Ages 5–10 **The move:** COACH-07 Scratch Night. Scratch is a block-based programming environment for children; ScratchJr is a simpler version for the youngest.^[13](#note-13)^ With an eight-to-ten-year-old, build one tiny project together—a cat that walks across the screen and says hello—where *they* drive the mouse and *you* ask the questions. CodeAI (formerly Code.org) offers block-based courses for this age too. Use an offline editor or an account you manage as the parent. **Exact words:** "What do you think the cat will do when you click the flag?" and, when it doesn't: "What did it do instead? Which block do you think did that?" **One thing to avoid:** taking the mouse. Sit on your hands if you must. Your role is the question-asker; their hand on the mouse is the whole point. ### Ages 11–14 **The move:** co-learn a function side by side (COACH-06 Co-Learning Hour). Pick a small spec together—"a function that tells you whether a number is even"—and each write your own version in your own file. Then trade, predict what the other's will do on three inputs, and run them. **Exact words:** "Let's both write it, then guess what each other's does." And when yours is wrong—it will be, sometimes, and that's a gift—"Ha. Mine broke on zero. Let me log it." **One thing to avoid:** writing yours first and then "helping." Write at the same time, or let them go first. Being visibly wrong in front of your child, calmly, is one of the most valuable things you can model. ### Ages 15–18 **The move:** ask them to show you the docs line. When your teen solves something, ask: "Where did you find that? Show me the line in the documentation." This is PY-06 in reverse, and it does two jobs: it nudges them toward the official source, and it tells you, without any spying, whether they understood the answer or just copied it. **Exact words:** "That's neat—show me the line in the docs that told you how." If they used an AI tool: "Great—what did it say, and how did you check it?" **One thing to avoid:** treating "I looked it up" as cheating. Looking it up is what working programmers do all day. What matters is that they can explain what they found. If your teen is ready for more, *Computing for Emerging Adults*, Chapter 4, "Objects and Classes: The Bridge to Java," takes this chapter's index-card class much further, including into Java. It makes a fine side-by-side project: you design the cards, they write the code, and you each explain the other's half. ## If it isn't clicking **Syntax errors swamp you.** Every run is a wall of red text. Type less and run more: one new line, then run; one more line, then run. When an error appears, read only its last line first. Here's one: ``` TypeError: can only concatenate str (not "int") to str ``` That came from `print("2" + 3)`. In plain words: you tried to join text and a number with `+`, and Python won't guess which you meant. The line number above that last line tells you where. Chapter 3 teaches reading these reports—they're called tracebacks—from the bottom up. **Functions confuse you.** Write the *call* before the function. Write `print(scale(2, 4, 6))` and the answer you expect (`3.0`) first, as a comment. Then write the function to make that line true. The call is the spec. **The documentation feels impenetrable.** Read only the examples. Copy one, run it, change one thing, and run it again. Come back to the prose later; it makes much more sense once you've seen the example work. **When to get a person.** First run the rescue order from **The Computing Hour**: reread your spec, wait, hint, a worked example in a scratch file, then back to your own file. If two logged sessions are stuck on the same thing, bring the log to a person—a library coding group, a meetup, a friend who codes. Show them your Debug Log page. Most people who code are delighted to be asked a precise question, and your log makes your question precise. **Indentation errors keep appearing.** Python reads the spaces at the start of a line as meaning: they say which lines belong inside a function, a loop, or an `if`. An `IndentationError` almost always means two lines that should line up don't, often because one was indented with a tab and the other with spaces after a paste. Set your editor to insert four spaces when you press Tab, then retype the leading spaces on the line Python names and the line above it. Read the block aloud as you go: "this line is inside the loop; this one runs after it." If you can't say which block a line belongs to, Python can't either. **Names keep tripping you up.** A `NameError` means Python met a name it has never been told about. Nine times in ten it's a spelling or capitalization difference (`total` and `Total` are different names to Python) or a variable used before the line that creates it. Circle every name in the function on paper, and draw an arrow from each use back to the line where it was first given a value. A name with no arrow is your bug. ## Tools, including AI **Editors.** Thonny is gentle for beginners and has a step-through debugger. Any plain-text editor works with Python 3 installed. Check the current version of whatever you install. **Seeing a trace.** Python Tutor is a website that shows a short program running one step at a time, with every variable drawn as a box—an animated trace table.^[3](#note-3)^ It's excellent for the recipe scaler and the counting program. **Official answers.** docs.python.org: the tutorial for learning, the library reference for looking things up. **AI.** Everything in the AI box in **The Computing Hour** applies. What's specific to this chapter: AI tools are useful for *explaining* an error message you've already read yourself, and risky for *writing* the functions this chapter asks you to write, because the whole point of these exercises is the struggle that builds your picture. Try first, with the timer. If you then ask a tool to explain `TypeError: can only concatenate str (not "int") to str`, log it. If a tool suggests code, keep it only after you can explain every line and it passes your examples. ### In-home — CAREER-03 Automate One Chore - **Time:** 75 minutes (deep) - **Materials:** your learning folder; a stopwatch; a copy of the files the chore uses - **Safety and privacy:** work on copies, never the originals; at work, only within your employer's rules on tools and data - **The fun:** watching a computer do in seconds a job that used to eat your Sunday evening - **The skill:** turning a real chore into a spec, a small script, and a before-and-after time note - **The crumb:** the script and a before/after time note **How it goes.** When you're comfortable with files and functions, this is the chapter's capstone. Choose one small, boring, repeated chore: totaling a monthly mileage log, writing next week's chore list to a file from Chapter 1's picker, counting how many books each child read this month from a reading list. Time yourself doing it by hand once, and write the time down. Then write a SPEC-01 spec for the script, with a done line ("given last month's file, it prints the same total I got by hand"). Build it in small steps, predicting before every run. Work on a *copy* of the real file until the script has passed your examples at least twice; a script that changes files can make a mess faster than any person. Finally, time the scripted version, and write both times on one line in your log. Expect the first version to take longer than the chore itself. That's normal and it isn't the point: the script runs next month, and the month after, and you can explain every line of it. That before-and-after note is one of the most satisfying entries you'll ever put in a portfolio. ### Blocked, round two: a mileage log If you'd like one more round of blocked practice before the capstone, build a mileage log from a made-up file with one trip's miles per line. Three functions, each with a docstring and two examples written first: one that reads the file into a list of numbers, one that returns the total, and one that returns the longest trip. For a file holding `12.5`, `30`, and `7.5`, predict the total and the longest trip before you run anything. (They're `50.0` and `30.0`; if your longest trip prints as `30` without the decimal point, look at how you turned each line into a number—`float()` and `int()` give different types, and noticing which one you used is exactly the kind of detail this chapter trains.) ## What "done enough" looks like You're ready for Chapter 3 when you have: - [ ] a clean learning folder with a backup copy (START-04) - [ ] a program that reads a file and writes a report (PY-04) - [ ] at least one function with a docstring and a return value, tested with examples you wrote first (PY-03) - [ ] a list-or-dictionary choice card with reasons (PY-05) - [ ] one docs note: the line from the official documentation that answered a question (PY-06) - [ ] a class designed on index cards and then written (PY-07) - [ ] at least three Debug Log pages - [ ] AS-01 Cold Trace once: trace a short program you haven't seen and predict its output, unaided - [ ] AS-02 Debug on the Spot once: a partner plants a bug (`print` instead of `return` is a good one), and you fix it while explaining aloud - [ ] AS-04 Explain Your Code once: walk a partner through your file-counting program, line by line Place yourself by these skills, not by the calendar. If the file program and one function feel solid, move on; you'll use everything here again in Chapters 3 and 4. \newpage # Chapter 3 ## Testing and Debugging: Proof Before Pride ![A test table ruled into columns with check marks and one red cross, a magnifying glass, a small rubber duck and a pencil — still life, no people, no logos, no readable text.](art/ch03-opener.jpg){width=100%} ## Why this matters Up to now you've written programs and watched them run. From here on, every program you write comes with a promise attached: a short table that says, before you type a line, what the program should do for each kind of input. Then you make the computer check the promise for you. That's testing. When the check fails, you read the evidence, write down one honest guess, and try one change. That's debugging. This chapter teaches both, and it teaches them as a calm habit rather than a crisis. Here's why it matters for you, as an adult with limited evenings. Without tests, you finish a session not knowing whether your program works. You think it does, because it printed something plausible. Next week you come back, change one line, and something else breaks quietly. You lose the evening hunting. With tests, you finish a session knowing exactly which promises hold. You come back next week, change a line, run the tests, and know in two seconds what you broke. Tests are how a busy person keeps their progress. There's a deeper reason too. Researchers who reviewed decades of work on how people learn to program found that the difference between novices who make progress and novices who stall is mostly strategy, not talent.^[1](#note-1)^ The effective ones test, trace, and work from evidence. The stalled ones change things at random and hope. That's good news, because strategy can be learned in an evening and practiced in fifteen minutes. You don't need a gift for this. You need a table, a pencil, and the patience to read the last line of an error message. This chapter also carries something the earlier chapters only touched: the feeling of being wrong. Many adults learning to program catch themselves thinking some version of "I'm just bad at this." The program fails, the red text appears, and it feels like a verdict on you. It isn't. A bug is information about the program, not about the person who wrote it. Working programmers meet programs that don't work yet all the time. The skill isn't avoiding bugs. The skill is meeting them with curiosity. That's the voice of **The Computing Hour**—*oh, a clue*—and this is the chapter where it earns its keep. And if you're teaching or learning beside a child, this is the chapter you'll use most. Children meet bugs constantly, and how the adult nearby reacts teaches them more than any lesson. If you can say "Huh, it surprised us—let's write down what we expected" in a steady voice, you've given them the most useful habit in computing. You'll find exact words for each age in the coaching section. One honest limit before we start. Testing doesn't make a program perfect. A test only checks the cases you thought to write down. What tests give you is something more modest and more useful: proof that the promises you wrote are kept, and a fast alarm when one breaks. Proof before pride—that's the title, and it's the whole idea. ## Understand it yourself ### The plain picture A test table is a promise written down before you cook. Picture a recipe card that says "bake until done." Two cooks, two cakes. Now the card says "bake about 35 minutes; it's done when a toothpick comes out clean." That last line is a test. It's written before anyone bakes, anyone can run it, and it gives the same answer no matter who holds the toothpick. A test table is a page of toothpicks for a program: for this input, it should give this output. A **test** is a written check comparing what the program does with what it should do. You write a handful of them in a table, then turn each row into one line of code that the computer runs. ### The precise picture Good test tables cover three kinds of input: - **Normal** inputs—the ordinary cases the program exists for. - **Boundary** inputs—the values right at the edge of a rule. If the rule is "50 or more," the boundary is 50, and its neighbors 49.99 and 50.01 are worth a look too. - **Invalid** inputs—things that shouldn't happen but will: a negative number, an empty list, text where a number belongs. An **edge case** is an input at the boundary, or an odd one a careless user might type. Most real bugs live at edges, which is why the table makes you write them down before you're tired. Here's a test table for a small household rule. Picture a family that lets the kids order a book from a catalog, with free shipping on orders of 50 or more. (The threshold is made up for practice.) | Input | Kind | Expected | Why | |---|---|---|---| | 60 | normal | True | well above | | 40 | normal | False | well below | | 50 | boundary | True | "50 or more" includes 50 | | 49.99 | boundary | False | just under | | −5 | invalid | an error | an order can't be negative | Notice the last column. "Why" is where you discover what your spec really says. Writing "50 or more includes 50" forces the question every boundary hides: is it *more than* or *at least*? ### Asserts: making the table run Python has a one-word way to turn a row into a check: `assert`. It takes something that should be true. If it is, nothing happens. If it isn't, the program stops loudly. Here is the shipping rule, written the way many people first write it. The bug is deliberate, and it's labeled: ```python def free_shipping(order_total): """True when the order ships free: 50 or more.""" return order_total > 50 # DELIBERATE BUG: 50 itself is left out assert free_shipping(60) == True assert free_shipping(40) == False assert free_shipping(50) == True print("all shipping tests passed") ``` Predict before you run. If you read carefully, you'll guess that the third assert fails, and it does. Python stops and prints a traceback whose last line is just `AssertionError`, pointing at line 7, the `free_shipping(50)` row. The words "all shipping tests passed" never appear. One change—`>` becomes `>=`—and the run prints `all shipping tests passed`. That's the whole mechanism. You'll learn fancier testing tools later if you want them, but plain asserts in a file are enough for everything in this book. ### Three kinds of error Programs go wrong in three ways, and naming them calms everyone down: - A **syntax error** means Python can't read the code at all—a missing colon or bracket—so nothing runs. - A **runtime error** means the program starts, reaches a line it can't carry out, and stops with a message. - A **logic error** means the program runs, finishes, and gives the wrong answer. No red text. Only a prediction or a test catches it. The shipping bug is a logic error. Without the test, the function would have run happily for years, quietly charging shipping on exactly-50 orders. Logic errors are why tests exist. ### How to read a traceback A **traceback** is Python's report of where an error happened, read from the bottom up. Here's a runtime error from a function that averages a list of scores: ```python def average(scores): """Return the mean of a list of numbers.""" return sum(scores) / len(scores) print(average([8, 9, 10])) print(average([])) ``` The first call prints `9.0`. The second stops the program. The traceback looks like this (your file path will match your own folder): ```text Traceback (most recent call last): File "avg.py", line 6, in print(average([])) File "avg.py", line 3, in average return sum(scores) / len(scores) ZeroDivisionError: division by zero ``` Recent versions of Python also print small carets and tildes under the part of each line that failed; we've left them out so the shape is easy to see. Read it in this order: 1. **The last line** says what happened: the error's name and a message. `ZeroDivisionError: division by zero`. 2. **The line just above it** says where: line 3, inside `average`. 3. **Further up** says how the program got there: line 6 called `average` with an empty list. The official Python tutorial puts it plainly: the last line of the message tells you what happened.^[14](#note-14)^ The place Python reports isn't always the place that needs fixing, though. Here the division on line 3 is where it broke, but the real question is a spec question: what *should* the average of no scores be? Nothing? Zero? An error with a friendly message? The traceback found the edge; your spec has to decide it. ### The Debug Log, used for real You met the Debug Log in **The Computing Hour**: one page per bug, dated, with **Expected** / **Actual** / **Guess** / **One change** / **Result**. This chapter is where it becomes a habit. Here's the shipping bug as a log page. *An illustration, not a reported family:* a filled Debug Log page. > **Expected:** `free_shipping(50)` gives True (spec: "50 or more") > **Actual:** AssertionError on line 7 > **Guess:** I used `>` and the spec means "at least" > **One change:** `>` to `>=` > **Result:** all three asserts pass; "all shipping tests passed" printed Five lines, two minutes. The page does three things for you. It slows you down at the exact moment panic wants to speed you up. It forces one change instead of three. And it leaves a record, so next month when a similar bug appears, you can flip back and find your own past solution. ### Wrong answers you should be able to hear These are the five you'll hear most, in yourself or in your child. Each has a calm reply. - **A test that always passes.** If a test can't fail, it proves nothing. Say: "Can I make this test fail on purpose?" - **Changing three things at once.** If it starts working, you don't know which change mattered; if it gets worse, you don't know which one hurt. Say: "Which one change will I try first?" - **Reading the top of the traceback and stopping.** The top is the oldest part of the story. Say: "Let's read it from the bottom." - **"It works on my machine."** Without a written test, "works" means "it printed something once." Say: "Which test shows that?" - **"I'll just start over."** Rewriting from scratch to escape a bug usually rebuilds the same bug, because the misunderstanding comes with you. Say: "Log what I expected and what happened first." ### A five-minute warm-up Print the `average` traceback above, or copy it by hand. With a pencil, number the lines from the bottom: 1 for the error line, 2 for the line above, and so on. Next to line 1 write what happened in your own words. Next to line 2 write where. Next to the top write how the program got there. That's the whole skill of reading red text, and you've just done it on paper. ## How to run it this week From this week on, every Computing Hour has a test table in it. That's the one new rule, and it slots into the steps you already know: **Specify.** Write the spec as before, then add a test table under it: two normal rows, one or two boundary rows, one invalid row. If you can't fill the "Expected" column, your spec isn't finished. That's not a failure—that's the table doing its job early. **Predict.** Before running, mark each row with your prediction: pass or fail. On a first run, most of them should fail, because you haven't written the function yet. **Build and Test.** Turn each row into an assert. Write the function a little at a time. Run after every few lines. Watch the asserts go from failing to passing. **Debug and Log.** Any surprise gets a Debug Log page—every one, even the ones you fix in thirty seconds. Five quick pages teach you more than one heroic evening. **Explain and File.** Say which tests pass, which you'd add next, and what help you used. File the test file next to the program, in both places you keep your work. ### Session 1 (micro, about 15 minutes): Test Table Before Code Write the table before any code. The card below is the whole session. ### In-home — TEST-01 Test Table Before Code - **Time:** 15 minutes (micro) - **Materials:** Notebook, pencil, a spec you wrote in Chapter 1 or 2 - **Safety and privacy:** Made-up data only. - **The fun:** Catching a hole in your own spec before the computer does - **The skill:** Normal, boundary, and bad inputs with expected results, written first - **The crumb:** Test table **How it goes.** Pick a small spec you've already written—the recipe scaler, a chore picker, a word counter. Draw five rows with four columns: Input, Kind, Expected, Why. Fill two normal rows first; they're easy and they warm you up. Then find the boundary: what number, length, or count changes the answer? Write the row right at it. Last, write one invalid row: an empty list, a negative number, text where a number belongs. What usually happens is that one row's Expected column won't fill. You'll sit with the pencil over it, and realize you don't know what the program should do when the list is empty. Good. Write the question in the Why column and decide it—that decision goes back into the spec. Date the page. Next session, the table becomes asserts. ### Session 2 (micro, about 20 minutes): Asserts and the boundary Turn the table into asserts and let the computer check your promises. The worked session below is one version of it, using the shipping rule. ### Session 3 (micro, about 15 minutes): Read the Red Text BUG-01 Read the Red Text: take one traceback from this week—yours, or the `average` example above—and annotate it bottom-up on paper: what happened, where, and how the program got there. Then file it with your Debug Log pages. ### The words to say to yourself When a test fails, the Hour's opening question still leads: *"Before I change anything, ask anyone, or ask a tool: what did I expect, what actually happened, and what's the one change I'll try?"* For this chapter, sharpen it: "Which test failed, and what did it expect?" That question points you at a line number and a value, which is where the bug is. "Why is this broken?" points you at the whole universe. ### Worked session: the free-shipping boundary *An illustration, not a reported family:* A learner has about twenty minutes, split between a train ride home (as a passenger) and the kitchen table. **Specify (6 minutes).** In the notebook, on the train: > Free shipping. Input: an order total. Output: True if it ships free. Done when orders of 50 or more ship free, under 50 don't, and a negative total is an error. Underneath, the five-row test table from above. **Predict (1 minute).** At home, before running: "All three asserts pass." **Build and Test (5 minutes).** They type the function with `>` and the first three asserts, exactly as in the shipping example above. Run. `AssertionError`, line 7. **Debug and Log (4 minutes).** They don't touch the code. They read the last line, then the line number, then look at line 7: it's the `50` row. The guess comes fast once the line is in view. > **Expected:** `free_shipping(50)` gives True (spec: "50 or more") > **Actual:** AssertionError on line 7 > **Guess:** I used `>` and the spec means "at least" > **One change:** `>` to `>=` > **Result:** all three asserts pass; "all shipping tests passed" printed There's time for one more row. In the spec, a negative total is an error, so the function needs to say so: ```python def free_shipping(order_total): if order_total < 0: raise ValueError("order total can't be negative") return order_total >= 50 print(free_shipping(50)) # True free_shipping(-5) # stops: ValueError: order total can't be negative ``` The last line of the traceback now reads `ValueError: order total can't be negative`—a message the learner wrote, in plain words. The red text is on their side now. **Explain and File (3 minutes).** "I specified free shipping at 50 or more. I predicted all three tests would pass. Test three failed at the boundary; `>=` fixed it. Next I'd add the 49.99 row as a real assert. Help I used: none." Test file and program saved in two places. ### Stopping when the timer ends Stop on a passing test if you can, and on a written log page if you can't. If the timer goes off mid-bug, finish the Expected and Actual lines, write your current guess, and close the laptop. You've left yourself a perfect starting place. A logged stuck session is progress, not a failed evening. ## Practice that actually builds it Practice comes in two shapes. Blocked practice repeats one move until it's smooth; mixed practice asks you to choose the right move from several. You need both, in that order. ### Blocked: boundaries Spend two micro sessions writing nothing but boundary rows. Take five rules from daily life—"kids under 12 eat free," "the library allows up to 10 holds," "a password needs at least 15 characters"—and for each, write the boundary value, its two neighbors, and the expected answer. No code. You're training your eye to find the edge. ### Mixed: tests, then traces Once boundaries feel easy, mix them with tracing. Take a short function, write its test table, then trace it by hand for the boundary row before running anything. If your trace and your table disagree, one of them is wrong—and finding out which is the best kind of practice. ### Diagnose this: the test that can't fail Here's a test file someone handed in proudly. Every test passes. Find the one that proves nothing. ```python def double(n): return n + n assert double(2) == 2 + 2 assert double(0) == double(0) print("done") ``` It prints `done`. The second assert compares the function with itself. It would pass if `double` returned 0, or 99, or nonsense—it can't fail. The first is weak too: it checks the function against its own arithmetic. Rewrite them as plain answers you worked out by hand: `assert double(0) == 0` and `assert double(-3) == -6`. Both pass with the real function, and both would fail with a broken one. That's the test of a test: could it ever fail? ### Out-of-home — TEST-03 The Test That Can't Fail - **Time:** 10 minutes (micro) - **Materials:** The `double` example above, printed or copied; a pen - **Safety and privacy:** Made-up data only. Paper only—fine for a waiting room or a library table. - **The fun:** Playing detective on a test that looks fine - **The skill:** Spotting tests that prove nothing (always true, testing the test) - **The crumb:** Annotated example **How it goes.** Take the printed example somewhere you're waiting anyway—a practice, an appointment, a library table. For each assert, write one sentence in the margin: "This would fail if the function…" If you can't finish the sentence, the test can't fail. Circle it. Then write the replacement assert with a number you worked out yourself. Most people find the second assert quickly and miss the first. The first one is the sneaky kind: it passes, it looks reasonable, and it uses the same arithmetic as the code, so a mistake in your thinking would appear in both. Write "use a worked-out answer, not the formula again" at the bottom. That's the crumb. ### In-home — TEST-04 Break It on Purpose - **Time:** 20 minutes (micro) - **Materials:** Your shipping file (or any file with passing asserts), your Debug Log - **Safety and privacy:** Practice folder only. - **The fun:** Being the one who breaks it, for once - **The skill:** Changing one line to make a test fail, then restoring it - **The crumb:** Before/after note **How it goes.** Open a file whose asserts all pass. Before you touch anything, predict: "If I change `>=` back to `>`, which test will fail?" Write the row number. Make the change. Run. Did the test you named fail—and only that one? Put the line back and run again to watch everything pass. Then try a second break: change `50` to `5`. Predict first. This time the 40 row fails, because 40 now counts as free shipping. You've learned which tests guard which lines. If a change breaks nothing, that's important news: no test is guarding that line. Write a new row for it. The crumb is a two-line note: "Changed X, expected test N to fail, test N failed." ### In-home — TEST-02 Asserts That Fail Loudly - **Time:** 30 minutes (desk) - **Materials:** A test table from TEST-01; your editor - **Safety and privacy:** Made-up data only. - **The fun:** Watching the failures turn into passes, one at a time - **The skill:** An assert for each test-table row; reading a failing assert - **The crumb:** Test file **How it goes.** Turn every row of your table into one assert line. Put them under the function, as in the shipping example. Write the function in small steps and run after each. You'll see the first failing assert stop the file; fix that one, run, and see the next. Resist fixing ahead of the evidence. One detail helps when there are many asserts: you can add a short message after a comma, and Python prints it when the assert fails—`assert free_shipping(50) == True, "50 should ship free"`. When the file is green, file it beside the program with a dated name. That file is the crumb, and it's the proof you'll show in your portfolio. ### In-home — TEST-05 Someone Else's Spec - **Time:** 15 minutes (micro) - **Materials:** A short spec someone else wrote—a partner, a friend, a teen, or a practice exercise from the official Python tutorial - **Safety and privacy:** Their permission to use it; made-up data only. - **The fun:** Finding the question the writer didn't think to answer - **The skill:** Writing tests for a spec you didn't write - **The crumb:** Dated test table **How it goes.** Read the spec once without a pencil. Then write the test table. You'll find it harder than writing tests for your own spec, because you can't fill gaps from memory. Every row where you hesitate is a gap in their spec, and it's worth a polite question: "When the list is empty, what should it do?" If the spec came from your teen, this is one of the most respectful things you can do with their work. You're not grading it; you're using it seriously. Hand back the table with the questions circled. ### In-home — BUG-04 Print to See - **Time:** 20 minutes (micro) - **Materials:** The deliberate-bug example below; your editor - **Safety and privacy:** Practice folder only. - **The fun:** Watching a variable change in front of you - **The skill:** Adding prints to watch a variable change, then removing them - **The crumb:** Before/after file **How it goes.** Here's a function that should count the words longer than a given length. The bug is deliberate and labeled: ```python def count_long(words, n): """Count words longer than n letters.""" count = 0 for w in words: if len(w) > n: count = count + 1 return count # DELIBERATE BUG: indented one level too far print(count_long(["oak", "maple", "birch", "elm"], 3)) ``` Predict: "maple" and "birch" are longer than three letters, so it should print `2`. It prints `0`. Add one line inside the loop, at the top: `print("checking", w, "count is", count)`. Run it. You'll see a single line—`checking oak count is 0`—and then the answer. The loop ran once. That's your clue: the function returned during the first trip around the loop. Move `return count` back four spaces so it sits under `for`, run, and it prints `2`. Now remove the print. Debugging prints are scaffolding, not part of the building. Save a before and after copy; that's the crumb. Some editors have a debugger that steps through a line at a time and shows every variable—Thonny's is gentle for beginners. Print first, because it's clear; try the debugger when you're curious.^[12](#note-12)^ ### In-home — BUG-03 Rubber Duck, Out Loud - **Time:** 10 minutes (micro) - **Materials:** Any buggy file; any object—a mug, a toy, a patient person - **Safety and privacy:** Practice folder only. - **The fun:** Solving the bug in the middle of your own sentence - **The skill:** Explaining code line by line to an object (or a patient person) until the bug shows - **The crumb:** One-line note of where it showed **How it goes.** Put the object on the table. Explain the code to it, line by line, out loud: "This line sets count to zero. This line goes through each word. This line checks if it's long. This line… returns. Oh." It sounds silly. It works far more often than it should, because saying a line forces you to say what it really does, not what you meant. Write one line in your log: "It showed at line 7, when I said 'returns' out loud inside the loop." If you're doing this with a teen, you be the duck. Your only job is to listen and say "And then?" ### The rescue order, with tests in hand This is the chapter where you'll use the rescue order from **The Computing Hour** most, both versions. Use the order for yourself as written there; with tests, its "worked example in a separate scratch file" step becomes especially powerful—a three-line program that reproduces the same failing assert often makes the bug obvious. With a child, use the Hour's child version, and let the failing test be the hint: "Which test does the red text name?" COACH-03 The Rescue Order (in the Hour) is the card for rehearsing it. ### Talk to yourself (this chapter) **Opening:** "Which test failed, and what did it expect?" **Follow-ups:** 1. **Prediction** — What did I write in the Expected column before I ran it? 2. **Evidence** — What does the last line of the traceback say, and which line number does it name? 3. **Location** — On that line or the one above it, where do the value I expected and the value I got first part ways? 4. **Change** — What's the one change I'll make, and which test do I expect it to fix? 5. **Revision** — Was the test wrong, or the spec fuzzy, instead of the code? **How to wait:** Set a five-minute timer. Trace the failing row by hand on paper, one line at a time, writing each variable's value. Read the spec aloud. If the timer rings and you're still lost, stand up, get water, and come back to the log—not the code. **What a stuck silence usually means:** You're looking at the wrong line. Go to the line number in the traceback and read it slowly, then the line above it. If it's a logic error with no traceback, the bug is often in a line you're sure is fine—go there first. **Don't say / say instead:** Don't say "It's broken." Say instead "Test three expected True and got False." ## Coaching your kids at every age You don't need to be ahead of your child to coach debugging. You need to be calmer than the bug. Each age below has one move, the exact words, and one thing to avoid. ### Ages 5–10 **The move:** a bug hunt on paper, with your hands in your lap. Young children's programs are often paper strips—arrows for "step forward," "turn left"—or a few blocks on a screen. Plant one mistake in a strip you wrote: an extra turn, a missing step. Hand it over and say, "This robot was supposed to reach the cookie, but it bumped the wall. Can you find the step that went wrong?" Then wait. Let them walk it with a finger or a toy. **Exact words:** "What did you think it would do? What did it do? Where did they stop matching?" And when they find it: "You found the clue. What would you change?" **One thing to avoid:** grabbing the pencil. Even a gentle "here, let me show you" teaches that bugs are fixed by grown-ups. Sit on your hands if you need to. ### Out-of-home — BUG-05 Bug Hunt With a Child - **Time:** 15 minutes (micro) - **Materials:** Two paper strips of arrow steps (one correct, one with a planted mistake), a toy or coin to move, a grid drawn on paper - **Safety and privacy:** Paper only; no screens, no photos of the child posted anywhere. - **The fun:** The child gets to catch the grown-up's mistake - **The skill:** Finding a planted mistake in a young child's paper program without grabbing the pencil - **The crumb:** Child's corrected strip **How it goes.** This one travels well—to a grandparent's table, a library children's room, a waiting area with a little space. Draw a small grid with a start square and a goal. Give the child your strip with the planted mistake and the toy. "Let's run my program." They move the toy step by step. When it goes wrong, they'll usually laugh. Ask: "Which step was the bug?" Let them circle it and write the fix in their own way—a new arrow, a scribble, a word. Keep the strip. Write the date on the back. If you're doing it with two children, let the older one plant the bug for the younger one next time. The corrected strip is the crumb, and children are often proud to see it saved. ### Ages 11–14 **The move:** Expected and Actual on the log before you help. At this age, kids write real code and meet real tracebacks. When they call you over, don't look at the screen first. Look at the log. "Before I look—what did you expect, and what happened?" Have them write those two lines. Often they find the bug while writing them, and you never needed to look at all. **Exact words:** "Read me the last line of the red text." · "Which line number does it name?" · "What's the one change you want to try?" **One thing to avoid:** reading the traceback for them. Even if you can see the answer, the skill they need is reading it themselves. Your job is to point at the bottom line and ask. ### Ages 15–18 **The move:** read the log, not the screen. Teens working on longer projects keep Debug Logs of their own. When you sit with them, ask for the log page, not the laptop. Read one page and write one question on it—just one, in pencil, in the margin: "What made you guess the boundary?" or "Did this test exist before the fix?" That question is your contribution. It respects their ownership and shows them their log is real evidence, worth reading. If your teen is using it, *Computing for Emerging Adults*, Chapter 3, "Testing and Debugging: Proof Before Pride," runs this skill from the teen's side. **Exact words:** "Can I read your log from this week?" · "Which bug taught you the most?" · "Show me a test that would have caught it sooner." **One thing to avoid:** fixing their code over their shoulder. At this age, a fix you make is a fix they didn't learn—and, for their records, help you gave belongs on their log as "Help I used," just like a tool's. ### In-home — COACH-04 Read the Log, Not the Screen - **Time:** 15 minutes (micro) - **Materials:** Your teen's Debug Log (with their permission), a pencil - **Safety and privacy:** Their log, their permission; don't photograph or share it. - **The fun:** Seeing how your teen thinks - **The skill:** Reading a teen's Debug Log and asking one question about it - **The crumb:** Your one question written on the page **How it goes.** Ask, don't take: "Could I read a page of your log this week?" Pick one page. Read the Expected, Actual, and Guess lines. Then write a single question in the margin, small and in pencil. Hand it back. What usually happens is that the teen answers the question out loud before they've finished reading it, and you end up having the best five-minute conversation of the week. If you practice on your own log first, you'll know which questions are useful: the ones about guesses and tests, not about style. ## If it isn't clicking **Tests feel pointless.** If writing tests feels like busywork, you probably haven't seen one catch a bug you'd have missed. Do TEST-04 Break It on Purpose and TEST-03 The Test That Can't Fail back to back. Watching a good test catch your planted bug, and a bad test sleep through it, usually changes your mind in one session. **Tracebacks overwhelm you.** Read only the last line, then the line number. Ignore everything else for a week. Copy the last line into your log in your own words. After ten tracebacks, the rest of the report will start making sense on its own. **Debugging spirals.** If you notice you've changed four things and lost track, stop at the timer and log. Put the code back to the last version where you knew what was happening (Chapter 6 will make this painless). Then walk the Hour's rescue order for yourself from the top, and make one change, run, and write the result. The spiral breaks the moment you write. **When to get a person.** After two logged sessions stuck on the same thing, ask a human: a library coding group, a meetup, a community-college lab, or a friend who programs. Bring the spec, the test table, and the log pages. People who help beginners love a learner who arrives with a log; it makes helping fast. There's no shame in asking. Asking well is a skill too. ## Tools, including AI The AI box in **The Computing Hour** holds the rules; here's only what's different for testing. A tool can be very useful for reading a traceback you don't understand. Paste the error—not your private files—and ask what the error type means. Then go back to your own code and find the line yourself. A tool can suggest test cases you missed. That's a good use: you still decide whether each suggested row matches your spec, and you write the Expected column yourself. Be careful about the opposite use. Asking a tool to "fix the failing test" sometimes returns a changed test instead of a fixed function—a test that can't fail, made by a tool. Developers surveyed about AI tools commonly report that debugging AI-written code takes extra time; Chapter 8 looks at that honestly. For your editor, a beginner-friendly one with a step-through debugger, such as Thonny, is enough. Python Tutor can draw your program's variables as it runs, which is wonderful for a stubborn trace.^[3](#note-3)^ Check each tool's current version and terms before you rely on it. ## What "done enough" looks like You're ready to move on when you have: - [ ] A test table written **before** the code, for at least two programs, with normal, boundary, and invalid rows - [ ] A test file of asserts that fail loudly and now all pass - [ ] One rewritten test that used to be unable to fail - [ ] Five dated Debug Log pages, each with one change and its result - [ ] One traceback annotated bottom-up in your own words - [ ] **AS-01 Cold Trace** once: trace one tested function by hand, no computer, and match the asserts - [ ] **AS-02 Debug on the Spot** once: with no tool open, find and fix a planted bug using the traceback and one Debug Log page - [ ] **AS-04 Explain Your Code** passed once: with no tool open, explain every line of one tested function to a person (or out loud to the duck), including why each test row exists Placement is by skill, not by how many weeks you've spent here. If you can already do all of this, move on to Chapter 4. If one line is still shaky, give it two micro sessions and check again. "Done enough" means ready for the next chapter—you'll keep testing for as long as you program. \newpage # Chapter 4 ## Data: Spreadsheets, Questions, and SQL ![Two printed tables joined by a drawn line between their key columns, a bar-chart card and a ruler — still life, no people, no logos, no readable text.](art/ch04-opener.jpg){width=100%} ## Why this matters You already work with data. Maybe it's a household budget, a spreadsheet of who's driving which carpool, a club roster, a reading list, or a sheet at work that someone else built and everyone is afraid to touch. Most adults have spent more hours inside spreadsheets than inside any programming language. This chapter starts from that experience and makes it sturdier. The central idea is simple and easy to forget: **a question comes before a chart.** Data doesn't speak. People ask it questions, and the answer depends on the question, on which rows you kept, and on how carefully you cleaned the file. Start with the chart and you'll find a story that isn't there. Start with the question—written down, with what would change your mind—and the data has a chance to tell you something true. From there the chapter moves in a straight line. You'll make a table tidy: one row per thing, one column per fact. You'll clean a messy household-style file and keep notes on every change. You'll draw a chart that tells the truth. Then you'll let Python total a column from a CSV file, which is where data meets the programming you learned in Chapter 2. Finally, you'll draw a small database on paper and ask it questions in SQL, the language most databases speak, including the one join that connects two tables. Why learn code for this when spreadsheets exist? You don't have to choose. A spreadsheet is wonderful for looking, sorting, and trying things. Code is better when you'll repeat the job every month, or when you need a record of every step so someone else—or you, in a year—can check how a number was made. Many careful people do both: explore in a spreadsheet, then write down the steps as code once they know what they want. There's a household reason, too. Your kids will meet data everywhere: charts in the news, survey results in school, numbers in advertising. An adult who asks "What question is this chart answering?" in a calm voice at the dinner table gives them a habit worth more than any formula. One honest limit: this is not data science in a chapter. It's the foundation underneath—honest questions, tidy tables, careful cleaning, simple totals, and a first conversation with a database. That foundation is enough for a great many real jobs at home and work, and it's the part people skip. And one safety rule runs through every page: **practice data is made up or public.** Don't practice on your real bank records, your children's health information, or anyone's personal details. Make a file of invented grocery trips, or download a public dataset from your town or library. If a practice file would embarrass anyone if it leaked, it's the wrong practice file. ## Understand it yourself ### The plain picture A tidy table has one row per thing and one column per fact. A row is one grocery trip, one library book, one child's practice session. A column is one fact about every row: the date, the amount, the title. If you can say "each row is one ___," your table is probably tidy. If you can't finish that sentence, it isn't. ### The precise picture Four ideas carry the rest of the chapter. - **Types.** Every column has a type—what kind of value it holds: whole numbers, decimal numbers, text, dates. A column that mixes "12.50" with "twelve fifty" and "12.50 (cash)" has no single type, and every total built on it is shaky. - **Keys.** A **database** is organized tables. A **key** is the column that links them—usually an ID number that names each row exactly once. Names make bad keys: two people can share a name, and one person can spell theirs two ways. - **Joins.** A **query** is a question asked of a database. A join is a query that connects two tables through a key: "for each loan, find its book." - **Aggregation.** Totals, counts, and averages squeeze many rows into one number. They're powerful, and they hide things. Always know how many rows went into a number. ### Messy to tidy Here's a messy table of the kind adults make every day. Picture a family tracking kids' activities: | Kid | Mon | Tue | Notes | |---|---|---|---| | Child A | piano 30 | — | soccer Sat 60 | | Child B | soccer 45 | piano 30, art 20 | | It's readable to the person who made it. It's nearly impossible to total. Days are spread across columns, one cell holds two facts ("piano 30"), another holds two activities, and Saturday is hiding in Notes. Here's the same information, tidy: | kid | day | activity | minutes | |---|---|---|---| | Child A | Mon | piano | 30 | | Child A | Sat | soccer | 60 | | Child B | Mon | soccer | 45 | | Child B | Tue | piano | 30 | | Child B | Tue | art | 20 | Each row is one activity session. Each column is one fact. Now "total minutes of piano this week" is a sort and a sum. ### Wrong answers you should be able to hear - **A chart before a question.** Someone opens the data and starts making charts to "see what's there." Say: "What question is this chart answering?" - **A truncated axis.** A bar chart whose vertical axis starts at 90 instead of 0 makes a 2-point difference look like a landslide. Say: "Where does this axis start?" - **One column holding two facts.** "piano 30" in a single cell. Say: "Can I split this into two columns?" - **A join with no prediction of row count.** You run a join and accept whatever comes back. Say: "How many rows did I expect, and why?" - **Averaging percentages.** One club has 1 of 2 members coming (50%), another has 9 of 10 (90%). The average of the two percentages is 70%, but 10 of 12 people overall are coming, about 83%. Say: "What are the counts underneath?" ### A five-minute warm-up Take any messy table you've made—or the activity table above—and redraw it on paper as a tidy table. Write at the top: "Each row is one ___." Count the columns. If any cell still holds two facts, split it. That's the whole skill in miniature. ## How to run it this week This week runs in three steps: a question, a clean file, and a first query. Each fits a single session. ### Session 1 (micro, about 15 minutes): A Question Before a Chart DATA-01. Specify, for data, means writing the question. On a card, write three things: the question ("Which store did we spend more at this month?"), the population ("our grocery trips, 1–31 October, made-up file"), and what would change your mind ("if one store is more than twice the other, I'll rethink where we shop"). Predict the answer before you open anything. ### Session 2 (desk, about 40 minutes): Clean a Messy Spreadsheet Open your practice file and make it tidy, keeping a list of every change. The card is below, after the worked session. ### Session 3 (desk, about 30 minutes): First SELECT SQL-02 (in Practice). Ask a small practice database three questions, each with a prediction written first. Each session still uses the Hour's steps—Specify, Predict, Build and Test, Debug and Log, Explain and File. For data, "test" often means checking a number by hand: total three rows yourself, then confirm that the program or spreadsheet agrees. ### The words to say to yourself The chapter's question is "What question am I answering, and what would change my mind?" When the numbers come back, say what they are in careful words: "In this file, for these rows, the total is…" rather than "The data says…" The first sentence is true. The second is a claim about the world. ### Worked session: grocery trips in a CSV *An illustration, not a reported family:* A learner has a weekend morning—a deep session, about 75 minutes. **Specify (10 minutes).** A question card: "How much did we spend on groceries in this made-up file, and at which store?" Prediction: "About 50 total; more at the warehouse." **Predict (5 minutes).** Before writing code, they make the practice file—three invented trips, saved as `trips.csv`, a plain-text table with commas between the columns: ```text date,store,amount 2026-10-03,Market,12.50 2026-10-07,Warehouse,30.25 2026-10-10,Market,7.25 ``` They total it by hand first: 12.50 + 30.25 + 7.25 = 50.00. That hand total is the test. **Build and Test (30 minutes).** The first program reads each row as a list and adds the third item. It's labeled as the deliberate bug, because it's the one the session is built around: ```python import csv total = 0 with open("trips.csv") as f: for row in csv.reader(f): # DELIBERATE BUG: header row read as data total = total + float(row[2]) print(round(total, 2)) ``` It stops with a traceback. The last line reads `ValueError: could not convert string to float: 'amount'`. The learner reads it bottom-up, as in Chapter 3: the word `'amount'` is the column heading. The program tried to turn the header row into a number. **Debug and Log (10 minutes).** > **Expected:** 50.0 > **Actual:** ValueError on the header row > **Guess:** the first row is the heading, not a trip > **One change:** use `csv.DictReader`, which reads the header as column names > **Result:** see below ```python import csv total = 0 with open("trips.csv") as f: for row in csv.DictReader(f): total = total + float(row["amount"]) print(round(total, 2)) ``` It prints `50.0`, matching the hand total. Notice the bonus: `row["amount"]` names the column, so the code reads like the question. With time left, the learner answers the second half of the question—spending by store—and writes a report file: ```python import csv totals = {} with open("trips.csv") as f: for row in csv.DictReader(f): store = row["store"] totals[store] = totals.get(store, 0) + float(row["amount"]) with open("report.txt", "w") as out: for store, amount in sorted(totals.items()): out.write(f"{store}: {amount:.2f}\n") print(open("report.txt").read(), end="") ``` It prints two lines: `Market: 19.75` and `Warehouse: 30.25`. The prediction was right about the warehouse. **Explain and File (10 minutes).** "I specified a total by store. I predicted about 50, more at the warehouse. It did: 50.0, with the warehouse at 30.25. Next I'd add a month column and a test with an empty file. Help I used: the csv module page in the Python docs."^[15](#note-15)^ ### In-home — DATA-02 Clean a Messy Spreadsheet - **Time:** 40 minutes (desk) - **Materials:** A made-up or de-identified household spreadsheet; a notebook for change notes - **Safety and privacy:** Made-up data only, or a copy with every name and account number removed. Never clean the original. - **The fun:** The moment a column you couldn't total suddenly totals - **The skill:** Fixing types, blanks, duplicates, and inconsistent labels in a household spreadsheet - **The crumb:** Before/after file with change notes **How it goes.** Make a copy first and name it so you'll know: `budget-practice-clean.csv`. Work in four passes, one problem at a time. **Labels:** sort each text column and look for near-duplicates—"Groceries," "groceries," "Grocery." Pick one spelling. **Types:** in each number column, find anything that isn't a plain number—"12,50" with a comma where the decimal point belongs, "12.50 cash," "about 20"—and fix or flag it. **Blanks:** decide for each blank whether it means zero, unknown, or "doesn't apply," and write the rule down. **Duplicates:** sort by date and amount and look for rows that appear twice. What usually happens is that one decision is genuinely hard: is that blank a zero or an unknown? Write the question and your choice in the change notes. Those notes are the crumb, and they're more valuable than the clean file, because they let anyone—including you next month—see how the numbers were made. ### Stopping when the timer ends Stop between passes, never in the middle of one. Write the next pass at the top of your change notes: "Next: duplicates." Save the file with today's date. A half-cleaned file with good notes is a perfect place to start next time; a half-cleaned file with no notes is a puzzle. ## Practice that actually builds it ### Blocked: SELECT and WHERE five SELECT queries with WHERE, one session, each predicted. Then do the same with cleaning: one session that fixes only labels, another that fixes only types. ### Mixed: which tool, and which chart? a session where you pick the tool—spreadsheet, Python, or SQL—for three questions and say why. A one-off look is a spreadsheet. A monthly report is Python. A question across two tables is SQL. There's no single right answer; what matters is that you can say why. Write the three questions, your tool choices, and one sentence of reasoning for each in your log. Next week, do one of them in a different tool and compare how long it took and how sure you felt about the answer. A good mixed session to try: take your cleaned practice file and answer the same question twice—once by sorting and summing in the spreadsheet, once with a short Python program. If the two answers match, you've tested both. If they don't, you have a perfect bug to log, and it's usually a blank, a duplicate, or a label spelled two ways that one method caught and the other didn't. ### Diagnose this: the truncated axis Picture a bar chart of two weeks' reading minutes: 92 and 94. The vertical axis starts at 90, so the second bar looks twice as tall as the first. Nothing in it is false, and the impression is wrong. The fix is one change: start the axis at zero, and the bars look nearly equal—which is the truth. Write that caption in your notebook: "Reading time was about the same both weeks." ### In-home — DATA-05 Python Reads a CSV - **Time:** 60 minutes (deep) - **Materials:** A made-up CSV of at least ten rows (grocery trips, reading minutes, practice sessions); your editor; a calculator - **Safety and privacy:** Made-up data only. Practice folder only. - **The fun:** A report that writes itself next month - **The skill:** Using the csv module to total a column and write a report - **The crumb:** Program and report **How it goes.** Repeat the worked session above with your own made-up file, but larger. Start with a question card. Total three rows by hand and write the subtotal; that's your first test. Write the program with `csv.DictReader`, run it on just those three rows (copy them into a tiny test file), and check it matches. Only then run it on the full file. Add one invalid case on purpose: a row with a blank amount. Predict what happens. (It stops with a `ValueError`, because an empty string isn't a number.) Decide what your spec says—skip it, count it as zero, or stop with a clear message—and write that rule in the program and in your change notes. The crumb is the program, the report file, and the tiny test file side by side. Next month, you'll change one filename and run it again. ### In-home — DATA-03 Tidy Tables on Paper - **Time:** 20 minutes (micro) - **Materials:** Paper, pencil, one messy table (yours, or the activity table above) - **Safety and privacy:** Made-up data only. - **The fun:** Untangling a table you've lived with for years - **The skill:** One row per thing, one column per fact; redesigning a messy table - **The crumb:** Redrawn table **How it goes.** Write "Each row is one ___" at the top of the page before you draw anything. Fill the blank. Then list the facts you know about each of those things; those become your columns. Redraw the table with three or four sample rows. If a column name has "and" in it, split it. Most people discover that their messy table was really two tables—a list of kids and a list of sessions, or a list of books and a list of loans. That discovery is the doorway to databases, and it's the first step of SQL-01 below. ### Out-of-home — DATA-01 A Question Before a Chart - **Time:** 15 minutes (micro) - **Materials:** A notebook; a public chart—on a library bulletin board, in a town meeting handout, in a newspaper - **Safety and privacy:** Public material only; no photos of people. - **The fun:** Reading a chart like a detective instead of a believer - **The skill:** Writing the question, the population, and what would change your mind before opening the data - **The crumb:** Question card **How it goes.** Find one public chart while you're out—at the library, a town meeting, a community center. Copy its title. Then, on a card, write the question you think it answers, the population (whose data? which years?), and one thing that would change your mind about its message. Check the axes: where does the vertical one start? Are the labels clear? What usually happens is that you can't write the population, because the chart doesn't say. That's useful knowledge. Write "population not stated" on the card. Next time, do the card *before* you look at your own data—that's the real habit. ### In-home — DATA-04 Chart That Tells the Truth - **Time:** 30 minutes (desk) - **Materials:** Your cleaned practice file; a spreadsheet program or paper and colored pencils - **Safety and privacy:** Made-up data only. - **The fun:** Making a chart you'd defend at a family meeting - **The skill:** Choosing a chart for the question; labeling axes; avoiding a truncated axis - **The crumb:** Chart with caption **How it goes.** Start with your question card. Pick the chart for the question: comparing a few categories is usually a bar chart; change over time is usually a line; parts of a whole only works if the parts truly add to the whole. Make it. Then label both axes with names and units, start bar charts at zero, and write a one-sentence caption that says what the chart shows and what it doesn't. ### SQL: asking a database questions A spreadsheet can hold one table nicely. When information naturally lives in two tables—books and loans, kids and sessions—a database keeps them apart and lets you join them with a key. SQL (often said "sequel" or spelled out) is the language for asking. SQLite is a small, free database that lives in a single file on your computer, which makes it ideal for practice.^[16](#note-16)^ ### In-home — SQL-01 A Paper Schema - **Time:** 20 minutes (micro) - **Materials:** Paper, pencil, a household collection—books, board games, tools you lend - **Safety and privacy:** Made-up names only ("Reader A"); no real neighbors' names. - **The fun:** Designing the catalog for your own shelves - **The skill:** Two tables and a key drawn on paper for a household collection - **The crumb:** Schema drawing **How it goes.** Draw two boxes. The first is **books**: id, title, shelf. The second is **loans**: id, book_id, borrower, due, returned. Draw a line from `loans.book_id` to `books.id`. That line is the key relationship: each loan points to exactly one book, and one book can have many loans over time. Fill three sample rows in each box. Then ask the paper two questions: "Which books are out right now?" and "How many times has each book been borrowed?" Trace your finger along the line to answer. If you can answer on paper, SQL is just writing down what your finger did. ### In-home — SQL-02 First SELECT - **Time:** 30 minutes (desk) - **Materials:** A practice database built from your schema (four books, five loans, all made up); SQLite - **Safety and privacy:** Practice folder only. Made-up data only. - **The fun:** Asking a question and getting exactly the rows you predicted - **The skill:** SELECT, WHERE, ORDER BY on a small practice database - **The crumb:** Saved queries file **How it goes.** Here's the practice library used in this chapter. The books are Bread at Home and Rivers of Stone (shelf "adult"), and Counting Stars and The Quiet Garden (shelf "kids"). Five loans: one each for Bread at Home, Rivers of Stone (already returned), and The Quiet Garden, and two for Counting Stars. Write the prediction first, then the query: ```sql SELECT title, shelf FROM books WHERE shelf = 'kids' ORDER BY title; ``` Prediction: two rows, alphabetical. Result: `Counting Stars | kids` and `The Quiet Garden | kids`. Read it aloud as English: "Show me the title and shelf, from books, where the shelf is kids, in title order." That's SQL's great kindness—it reads close to a sentence. Write three queries this way, each with a prediction comment above it (a line starting with `--` is a comment in SQL). Save them in a file. That file is the crumb. ### In-home — SQL-03 Join Two Tables - **Time:** 40 minutes (desk) - **Materials:** The same practice database; your paper schema - **Safety and privacy:** Practice folder only. Made-up data only. - **The fun:** A surprise row count that teaches you something real - **The skill:** An inner join answering a real question; predicting row count first - **The crumb:** Query with prediction **How it goes.** The question: which books are out, and when are they due? ```sql SELECT books.title, loans.due FROM books JOIN loans ON loans.book_id = books.id WHERE loans.returned = 0 ORDER BY loans.due; ``` Most people predict three rows: "three books are out." It returns four. Counting Stars appears twice, due on two different dates, because two readers each borrowed a copy and both loans are open. Nothing is broken. The join produced one row per *open loan*, not one per book. This is the most important lesson about joins: the row count follows the many side. Log it: Expected 3 / Actual 4 / Guess one book has two open loans / One change: none needed; the question was "which loans," not "which books" / Result: spec rewritten to say which. Then count, to check. `SELECT COUNT(*) FROM loans WHERE returned = 0;` returns `4`. Your hand count and the database agree. ### One step further: counting per book Once a join makes sense, you can ask "how many times has each book been borrowed?" This needs two new words. `GROUP BY` gathers rows into one group per book, and `COUNT` counts each group. A `LEFT JOIN` keeps books with no loans at all, so nothing quietly disappears: ```sql SELECT books.title, COUNT(loans.id) AS times_borrowed FROM books LEFT JOIN loans ON loans.book_id = books.id GROUP BY books.id ORDER BY books.title; ``` Prediction from your paper schema: Bread at Home 1, Counting Stars 2, Rivers of Stone 1, The Quiet Garden 1. That's exactly what comes back. If your prediction and the result disagree, trace the surprising book across the schema with your finger before touching the query. Don't worry if `LEFT JOIN` feels like a lot today; it's here so you know the shape exists. A plain `JOIN` and a careful prediction will carry you a long way. ### In-home — SQL-04 Keep Queries Safe - **Time:** 15 minutes (micro) - **Materials:** Notebook; the short example below - **Safety and privacy:** Practice database only. Never try this on any system you don't own. - **The fun:** Understanding one of the most common security mistakes in software - **The skill:** Why queries built by gluing strings are risky; parameters instead - **The crumb:** Two-line before/after **How it goes.** When a program asks a user for a book title and then looks it up, the risky way is to build the query by gluing in whatever the user typed. If someone types something that looks like SQL, it can become part of the query and change what it does. The safe way is to pass the user's text separately, as a parameter, so the database treats it only as data: ```python import sqlite3 con = sqlite3.connect("lib.db") cur = con.cursor() title = input("Title: ") cur.execute("SELECT id, shelf FROM books WHERE title = ?", (title,)) print(cur.fetchall()) ``` Typing `Counting Stars` prints `[(3, 'kids')]`. Typing something tricky that's meant to look like SQL prints `[]`—no book has that odd title, so nothing comes back. The `?` is the parameter's place, and the user's text fills it safely. Write the two-line before/after in your notebook in words: "Before: glue the typed text into the query. After: a `?` and the text passed separately." Chapter 7 comes back to this habit of mind.^[17](#note-17)^ ### Talk to yourself (this chapter) **Opening:** "What question am I answering, and what would change my mind?" **Follow-ups:** 1. **Prediction** — What number, or how many rows, did I write down before I ran it? 2. **Evidence** — What exactly came back, and how many rows went into it? 3. **Location** — Is the surprise in the data, in the cleaning, or in the question? 4. **Change** — What's the one change—to the query, the file, or the question—and what do I expect it to do? 5. **Revision** — Did my question card need to change instead? **How to wait:** Set a five-minute timer. Total three rows by hand. Count the rows with your finger. Read the question card aloud. **What a stuck silence usually means:** The table isn't tidy yet—one column is holding two facts, or one table is really two. **Don't say / say instead:** Don't say "The data says…" before you've checked it. Say instead "In this file, for these rows, …" ## Coaching your kids at every age Data is the friendliest computing topic for a family, because children have been sorting and counting since before they could read. ### Ages 5–10 **The move:** sort and tally real objects, then make a picture graph. Dump the sock drawer on the bed. "How should we sort these?" Let the child choose: by color, by owner, by whether they have a partner. Then tally—a mark for each sock—and draw a picture graph with one little sock per mark. Ask a question the graph can answer: "Which color do we have the most of?" **Exact words:** "What question can our graph answer?" · "How did you decide which pile?" · "Is there a sock that doesn't fit any pile?" **One thing to avoid:** choosing the categories for them. The child's categories—even "fuzzy" and "not fuzzy"—are real data design. Sorting by a rule they made up is exactly the skill. ### Ages 11–14 **The move:** an honest chart caption. When your child makes a chart—for a science project, a survey of friends, a sports season—ask for a one-sentence caption that says what the chart shows and what it doesn't. Then check the axes together. **Exact words:** "What question is this chart answering?" · "Where does the axis start?" · "How many people are in this?" **One thing to avoid:** telling them the chart is misleading. Ask the axis question and let them see it. A child who discovers a truncated axis remembers it; a child who's told forgets. ### Ages 15–18 **The move:** a paper schema review, with one question: "What's the key?" Teens working with databases often jump to typing queries. Ask to see the schema on paper first. Trace one question across the tables with your finger together. Then ask: "What's the key that links these?" and "How many rows will this join return?" If your teen is using it, *Computing for Emerging Adults*, Chapter 5, "Data: Questions, Tables, and Databases," carries this from the teen's side. **Exact words:** "Show me the schema before the query." · "What's the key?" · "Write the row count you expect, then run it." **One thing to avoid:** practice files with real family or friends' data. Teens often want to use real information because it's interesting. Help them make a convincing made-up version instead—that's a skill too. ## If it isn't clicking **Charts mislead you, or you're not sure what to chart.** Go back to the question card. Write the question, the population, and what would change your mind. Then pick the chart for the question. If you can't write the question, you don't need a chart yet. **SQL rows surprise you.** Predict the count every time, on paper, before running. Then count with `COUNT(*)`. A surprise is almost always a join following the "many" side, or a WHERE that's broader or narrower than you meant. Draw the schema and trace one surprising row. **Data feels personal or uncomfortable.** Switch to made-up data. It's not a lesser kind of practice; it's what careful professionals use for teaching and testing. Invent twelve rows in five minutes and keep going. **When to get a person.** First run the rescue order from **The Computing Hour**: reread your spec, wait, hint, a worked example in a scratch file, then back to your own file. If you've spent two logged sessions on the same cleaning or query problem, bring the question card, the change notes, and the query to a library group or a friend who works with data. They'll ask you "what's the key?" and "how many rows?"—and now you'll know why. ## Tools, including AI The AI box in **The Computing Hour** holds the rules; here's what differs for data. **Never paste personal or family data into an AI tool.** That includes budgets, health records, grades, and anything with a name on it. At work, the employer's rules come first; many forbid pasting work data into consumer tools. A tool can be good at explaining what a SQL query does, or suggesting how to fix a cleaning problem in a made-up sample. It's often fluent and wrong about the numbers themselves: a tool may "total" a column confidently and incorrectly. Check every number by hand on a few rows, or in code you can explain. For tools: a spreadsheet program you already have; Python's built-in `csv` module; and SQLite, which you can use from its own command-line program or from Python's built-in `sqlite3` module.^[16](#note-16)^ Check the current version and terms of any tool before relying on it. ## What "done enough" looks like You're ready to move on when you have: - [ ] A dated question card (question, population, what would change your mind) written before the data - [ ] A cleaned practice file with change notes for labels, types, blanks, and duplicates - [ ] One honest chart with labeled axes, a zero baseline for bars, and a one-sentence caption - [ ] A Python program that reads a CSV with `csv.DictReader`, matches your hand total, and writes a report - [ ] A paper schema with two tables and a key - [ ] Two SQL queries—one SELECT with WHERE, one JOIN—each with a written prediction of the rows - [ ] **AS-01 Cold Trace** once: trace the CSV-totaling program by hand on three rows, no computer, and match its output - [ ] **AS-02 Debug on the Spot** once: with no tool open, find and fix a planted bug in a short data program (a header counted as data is a good one) - [ ] **AS-04 Explain Your Code** once: explain every line of your CSV program and both SQL queries to a person, with no tool open Placement is by skill. If you already handle spreadsheets well, you may move through the first half quickly; give the SQL half its full time. "Done enough" means ready for the next chapter, not finished with data forever. \newpage # Chapter 5 ## Building for People: The Web ![A hand-drawn web page wireframe beside an open laptop, an index card and a pencil, near a window — still life, no people, no logos, no readable text.](art/ch05-opener.jpg){width=100%} ## Why this matters Everything you've built so far has had one user: you. You wrote the spec, ran the program, read the output, and decided whether it was right. A web page changes that. A page is something another person uses—someone who didn't read your spec, doesn't know what you meant, and may be using a keyboard instead of a mouse, a screen reader instead of their eyes, or a small phone in bright sunlight. The moment another person is the user, how you build changes. That's the real lesson of this chapter, and it's bigger than the web. Building for people means asking, before you type, "What does a visitor need first?" It means testing with someone who isn't you. It means noticing when "it looks fine to me" is the only evidence you have. Those habits make you a better builder of anything, and a far better first user of your children's projects. The technical part is pleasantly small. A web page is a plain text file. You can write one by hand, in any text editor, and open it in the browser you already have. No account, no installation, no cost. In a single desk session you can make a page with headings, a list, a link, and an image, and in a deep session you can add a button that actually does something. The building blocks are three languages that work together: - **HTML** is the outline: headings, paragraphs, lists, links, images. - **CSS** is the clothes: colors, spacing, fonts, layout. - **JavaScript** is the light switches: small bits of behavior that respond when someone clicks or types. You'll meet all three, in that order, and you'll learn to open the browser's console—the place where the page quietly reports its errors. Why hand-write pages when site builders exist? Site builders are perfectly good for publishing a club newsletter or a family blog. Use one if you need a site this week. But a builder hides exactly the things this chapter teaches: what a heading really is, why an image needs words, how a button knows it was clicked. Hand-written pages teach what the builder hides, and once you understand it, you'll use builders better too. One honest limit. You won't build a business website this weekend. You'll build a small, true, usable page—something a family member can open, read with a keyboard, and click without confusion. That's a real accomplishment, and it's the foundation everything bigger stands on. And one rule you'll see again at the end: nothing with family names, faces, school, or town goes public. Building a page and publishing a page are two different decisions. For a minor's work, publishing is always the adult's decision. ## Understand it yourself ### The plain picture HTML is the outline, CSS the clothes, JavaScript the light switches. Picture a printed recipe card. Its title is big and at the top. Its ingredients are a list. Its steps are numbered. Its photo has a caption. HTML says "this is the title, this is a list, this is a photo"—it describes the *structure*, not the looks. CSS says "make titles dark green and lists a little indented." JavaScript says "when someone presses the 'double it' button, double the amounts." ### The precise picture - **Elements.** HTML is made of elements written with tags: `

` starts a top-level heading and `

` ends it. `

` is a paragraph, `