Skip to content

Commit 2fd05d4

Browse files
travisjneumanclaude
travisjneuman
and
claude
committed
feat: add GETTING_STARTED, FAQ, VALIDATION guides; add time estimates and improve project instructions
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent cec5a40 commit 2fd05d4

35 files changed

Lines changed: 447 additions & 68 deletions

File tree

‎FAQ.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Frequently Asked Questions
2+
3+
Common questions from learners, with straight answers.
4+
5+
---
6+
7+
## Getting Started
8+
9+
### Do I need prior programming experience?
10+
11+
No. Level 00 starts from absolute zero -- it explains what a terminal is, what a file is, and what it means to run a program. If you have never written a line of code, that is exactly where this curriculum begins.
12+
13+
### What IDE or editor should I use?
14+
15+
[VS Code](https://code.visualstudio.com/) is recommended because it is free, cross-platform, and has excellent Python support. But any text editor works -- Sublime Text, PyCharm, Notepad++, even the terminal-based editors (nano, vim) if you prefer. The curriculum does not depend on any specific editor.
16+
17+
### What version of Python do I need?
18+
19+
Python 3.11 or newer. The setup guide ([03_SETUP_ALL_PLATFORMS.md](./03_SETUP_ALL_PLATFORMS.md)) covers installation for Windows, Mac, and Linux.
20+
21+
### Where do I start?
22+
23+
Open [START_HERE.md](./START_HERE.md). It will have you running Python in under 10 minutes. For a more detailed orientation, read [GETTING_STARTED.md](./GETTING_STARTED.md).
24+
25+
---
26+
27+
## Pacing and Progress
28+
29+
### How long will this take?
30+
31+
The full curriculum is approximately 400-500 hours of work. At 10 hours per week, that is roughly one year. At 5 hours per week, roughly two years. See [GETTING_STARTED.md](./GETTING_STARTED.md) for a detailed breakdown by level.
32+
33+
### Can I skip levels?
34+
35+
Not recommended. Each level builds on skills from the previous one. If you think you already know the material, run the diagnostic tool to find your appropriate starting level:
36+
37+
```bash
38+
python tools/diagnose.py
39+
```
40+
41+
This will test your knowledge and suggest where to begin.
42+
43+
### Do I need to do every single project in a level?
44+
45+
You should attempt all 15 projects in each level. The first few in each level reinforce core patterns, and the last one is a capstone that ties everything together. Skipping projects leaves gaps that show up later.
46+
47+
### How do I track my progress?
48+
49+
Run the progress tracker:
50+
51+
```bash
52+
python tools/progress.py
53+
```
54+
55+
You can also manually update [PROGRESS.md](./PROGRESS.md) as you complete projects.
56+
57+
---
58+
59+
## Expansion Modules
60+
61+
### Do I need to do all expansion modules?
62+
63+
No. Expansion modules are optional specializations. Pick the ones that match your interests or career goals. Modules 01-03 (Web Scraping, CLI Tools, REST APIs) are broadly useful. Modules like 10 (Django) or 12 (Cloud Deploy) are for specific career paths.
64+
65+
### What order should I do the modules in?
66+
67+
The [README](./README.md) has a suggested order based on prerequisites. In short: Modules 01-03 and 07 after Level 2. Modules 04-06, 08, 11 after Level 3. Modules 09-10, 12 after Level 5.
68+
69+
---
70+
71+
## Troubleshooting
72+
73+
### What if my tests fail?
74+
75+
1. **Read the error message.** The last line tells you what went wrong. The lines above it show you where.
76+
2. **Check the expected output.** Each project README shows what the output should look like.
77+
3. **Re-read the concept doc.** The project links to related concepts -- review those sections.
78+
4. **Add print statements.** Print the value of variables to see what your code is actually doing vs. what you expect.
79+
5. **Compare with the "Run" command.** Make sure you are in the right directory and using the correct command.
80+
81+
### I get "ModuleNotFoundError" -- what do I do?
82+
83+
This means Python cannot find a library you are trying to import. Common causes:
84+
85+
- You have not installed the required packages. Check if the project has a `requirements.txt` and run `pip install -r requirements.txt`.
86+
- You are not in a virtual environment. See the [Virtual Environments](./concepts/virtual-environments.md) concept guide.
87+
- You have multiple Python installations and pip installed the package to the wrong one. Try `python -m pip install <package>` instead of just `pip install`.
88+
89+
### I get "FileNotFoundError" -- what do I do?
90+
91+
Python cannot find the file you are trying to open. Common causes:
92+
93+
- You are not in the project directory. Run `cd` to the project folder before running the script.
94+
- The filename is misspelled. Check for typos, including capitalization.
95+
- The file path uses the wrong separator. On Windows, use forward slashes (`/`) or raw strings (`r"path\to\file"`).
96+
97+
### My code runs but produces wrong output
98+
99+
1. Print your variables at key points to see their actual values.
100+
2. Walk through your code line by line with a small example.
101+
3. Check if you are reading the right input file.
102+
4. Make sure you are not confusing `=` (assignment) with `==` (comparison).
103+
104+
---
105+
106+
## Curriculum and Licensing
107+
108+
### Can I use this curriculum in a classroom?
109+
110+
Yes. This curriculum is MIT licensed. You can use it for teaching, workshops, bootcamps, or any educational purpose. Attribution is appreciated but not required.
111+
112+
### I found a bug or broken link. How do I report it?
113+
114+
[Open an issue](https://github.com/travisjneuman/learn.python/issues) on GitHub. Include which file has the problem and what you expected vs. what you found.
115+
116+
### Can I contribute?
117+
118+
Yes. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. Bug fixes, improved explanations, and new test cases are especially welcome.
119+
120+
---
121+
122+
| [← Prev](START_HERE.md) | [Home](README.md) | [Next →](00_COMPUTER_LITERACY_PRIMER.md) |
123+
|:---|:---:|---:|

‎GETTING_STARTED.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# How to Use This Curriculum
2+
3+
This guide walks you through how the curriculum is organized, what order to follow, and how to pace yourself.
4+
5+
---
6+
7+
## Reading Order
8+
9+
Start with these four documents, in this order:
10+
11+
1. **[START_HERE.md](./START_HERE.md)** -- Install Python and run your first script in under 10 minutes.
12+
2. **[00_COMPUTER_LITERACY_PRIMER.md](./00_COMPUTER_LITERACY_PRIMER.md)** -- What a terminal, file, and program are. Skip this if you already know.
13+
3. **[01_ROADMAP.md](./01_ROADMAP.md)** -- The full program overview: every level, every milestone.
14+
4. **[03_SETUP_ALL_PLATFORMS.md](./03_SETUP_ALL_PLATFORMS.md)** -- Detailed setup instructions for Windows, Mac, and Linux.
15+
16+
After that, follow the "Next" link at the bottom of every document. The entire curriculum is a single click chain -- you never have to figure out what comes next.
17+
18+
## Reference-Only Documents
19+
20+
These documents are not meant to be read front-to-back. Use them when you need to look something up:
21+
22+
- **[02_GLOSSARY.md](./02_GLOSSARY.md)** -- Definitions of key terms. Come back here when you encounter unfamiliar words.
23+
- **[13_SAMPLE_DATABASE_SCHEMAS.md](./13_SAMPLE_DATABASE_SCHEMAS.md)** -- Example database schemas used in SQL-related projects. Relevant starting at Level 6.
24+
- **[concepts/](./concepts/)** -- Concept guides on variables, loops, functions, etc. Read these when a project references them or when you need a refresher.
25+
26+
---
27+
28+
## Time Estimates
29+
30+
How long each section takes depends on your pace and prior experience. These are rough estimates for someone working through the material carefully, including the "Alter it / Break it / Fix it" exercises.
31+
32+
| Section | Estimated Hours |
33+
|---------|----------------|
34+
| Level 00 (Absolute Beginner) | ~5 hours |
35+
| Level 0 (Terminal, Files, Basic I/O) | ~15 hours |
36+
| Level 1 (Input, CSV, JSON, Paths) | ~20 hours |
37+
| Level 2 (Data Structures, Cleaning) | ~20 hours |
38+
| Level 3 (Packages, Logging, TDD) | ~25 hours |
39+
| Level 4 (Schema Validation, Pipelines) | ~25 hours |
40+
| Level 5 (Scheduling, Monitoring) | ~25 hours |
41+
| Level 6 (SQL, ETL, Idempotency) | ~30 hours |
42+
| Level 7 (APIs, Caching, Observability) | ~30 hours |
43+
| Level 8 (Dashboards, Concurrency) | ~30 hours |
44+
| Level 9 (Architecture, SLOs, Security) | ~35 hours |
45+
| Level 10 (Enterprise, Production Readiness) | ~35 hours |
46+
| Elite Track (Algorithms, Distributed Systems) | ~40 hours |
47+
| Each Expansion Module (12 available) | ~10-20 hours |
48+
| **Total** | **~400-500 hours** |
49+
50+
---
51+
52+
## Weekly Pacing Suggestions
53+
54+
| Hours per Week | Approximate Duration |
55+
|----------------|---------------------|
56+
| 5 hours/week | ~2 years |
57+
| 10 hours/week | ~1 year |
58+
| 20 hours/week | ~6 months |
59+
| Full-time (40 hours/week) | ~3 months |
60+
61+
There is no rush. Consistent practice matters more than speed. It is better to spend 5 hours per week for two years than to cram for a month and burn out.
62+
63+
---
64+
65+
## What to Do When You Are Stuck
66+
67+
Getting stuck is normal. Here is a process that works:
68+
69+
1. **Read the error message.** Python error messages tell you exactly what went wrong and on which line. Read it from the bottom up.
70+
2. **Re-read the concept doc.** Every project links to related concept guides. Go back and re-read the relevant section.
71+
3. **Add `print()` statements.** Print the value of variables before the line that breaks. See what the data actually looks like.
72+
4. **Check the [FAQ](./FAQ.md).** Common problems and solutions are collected there.
73+
5. **Search the error message.** Copy the last line of the traceback and search for it online. Someone has hit the same error before.
74+
6. **Open an issue.** If you think the curriculum itself has a bug (broken test, missing file, unclear instructions), [open an issue](https://github.com/travisjneuman/learn.python/issues) on GitHub.
75+
76+
---
77+
78+
## How to Track Your Progress
79+
80+
Run the progress tracker from the repository root:
81+
82+
```bash
83+
python tools/progress.py
84+
```
85+
86+
You can also manually update [PROGRESS.md](./PROGRESS.md) as you complete projects.
87+
88+
---
89+
90+
## Choosing a Learning Mode
91+
92+
The curriculum supports three modes. Pick the one that fits how you learn:
93+
94+
- **Play-First** -- Open a project, tinker, break things, figure it out. Read the concept doc when you get stuck.
95+
- **Structured** -- Read the concept doc, take the quiz, then do the projects in order. Use checklists and mastery gates.
96+
- **Hybrid (Recommended)** -- Follow the structured path on weekdays. Explore expansion modules and challenges on weekends. Review flashcards daily.
97+
98+
---
99+
100+
| [← Prev](README.md) | [Home](README.md) | [Next →](START_HERE.md) |
101+
|:---|:---:|---:|

‎VALIDATION.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Curriculum Validation
2+
3+
This document explains how the curriculum's structure and integrity are validated, what each check does, and how to run them locally.
4+
5+
---
6+
7+
## CI Pipeline
8+
9+
The GitHub Actions workflow (`.github/workflows/curriculum-checks.yml`) runs two job groups:
10+
11+
### Quick Checks (runs on every manual trigger)
12+
13+
These checks validate the curriculum structure without running full project tests:
14+
15+
| Step | Script | What It Validates |
16+
|------|--------|-------------------|
17+
| Markdown link checks | `tools/check_markdown_links.sh` | All internal markdown links resolve to existing files. No broken cross-references. |
18+
| Root doc contract | `tools/check_root_doc_contract.sh` | Root-level documents (00-15) exist and contain required sections (title, navigation footer, etc.). |
19+
| Level index contract | `tools/check_level_index_contract.sh` | Each level's `README.md` lists all project directories in that level and links resolve correctly. |
20+
| Project README contract | `tools/check_project_readme_contract.sh` | Every project has a `README.md` with required sections: Focus, Run, Alter it, Break it, Fix it, Explain it. |
21+
| Project Python comment/docstring contract | `tools/check_project_python_comment_contract.sh` | Every `project.py` / `exercise.py` has a module-level docstring or comment explaining what it does. |
22+
| Portable path contract | `tools/check_portable_paths.sh` | No hardcoded absolute paths. All paths use `<repo-root>` placeholder or relative references. |
23+
| Elite track contract | `tools/check_elite_track_contract.sh` | Elite track projects have required structure: README, project.py, tests/, architecture docs. |
24+
| Project smoke checks | `projects/run_smoke_checks.sh` | Quick syntax check on all project.py files (imports parse, no syntax errors). |
25+
| Elite smoke checks | `projects/run_elite_smoke_checks.sh` | Same as above but for elite track projects. |
26+
27+
### Full Smoke (quarterly or manual trigger with `full_smoke=true`)
28+
29+
| Step | Script | What It Validates |
30+
|------|--------|-------------------|
31+
| Full curriculum checks | `tools/run_all_curriculum_checks.sh --full` | Runs all quick checks plus full test suites across all 165+ projects. |
32+
33+
---
34+
35+
## What "Pass" Means
36+
37+
A passing CI run means:
38+
39+
- Every markdown file that should exist does exist
40+
- Every internal link points to a real file
41+
- Every project has the required README sections and a commented/docstringed Python file
42+
- No hardcoded machine-specific paths exist in the curriculum
43+
- All Python files parse without syntax errors
44+
- (On full runs) All project test suites pass
45+
46+
It does **not** mean:
47+
48+
- The projects are pedagogically perfect
49+
- Every explanation is maximally clear
50+
- The curriculum covers every possible Python topic
51+
52+
---
53+
54+
## Running Checks Locally
55+
56+
### All quick checks at once
57+
58+
```bash
59+
bash tools/run_all_curriculum_checks.sh
60+
```
61+
62+
### Individual checks
63+
64+
```bash
65+
# Markdown links
66+
bash tools/check_markdown_links.sh
67+
68+
# Root doc structure
69+
bash tools/check_root_doc_contract.sh
70+
71+
# Level index structure
72+
bash tools/check_level_index_contract.sh
73+
74+
# Project README structure
75+
bash tools/check_project_readme_contract.sh
76+
77+
# Python file comments/docstrings
78+
bash tools/check_project_python_comment_contract.sh
79+
80+
# Portable paths (no hardcoded absolutes)
81+
bash tools/check_portable_paths.sh
82+
83+
# Elite track structure
84+
bash tools/check_elite_track_contract.sh
85+
```
86+
87+
### Smoke checks
88+
89+
```bash
90+
# Quick smoke (syntax check all project files)
91+
bash projects/run_smoke_checks.sh
92+
93+
# Elite track smoke
94+
bash projects/run_elite_smoke_checks.sh
95+
96+
# Full smoke (all projects, all tests)
97+
bash projects/run_smoke_checks.sh --full
98+
```
99+
100+
### Code quality
101+
102+
```bash
103+
# Lint all Python files
104+
ruff check .
105+
106+
# Run a specific project's tests
107+
cd projects/level-0/01-terminal-hello-lab
108+
python -m pytest tests/
109+
```
110+
111+
---
112+
113+
## CI Schedule
114+
115+
- **Manual:** Trigger anytime via GitHub Actions "Run workflow" button
116+
- **Quarterly:** Runs automatically on January 1, April 1, July 1, and October 1 at 06:00 UTC
117+
- **Full smoke:** Only runs on the quarterly schedule or when manually triggered with `full_smoke: true`
118+
119+
---
120+
121+
| [← Prev](CONTRIBUTING.md) | [Home](README.md) | [Next →](START_HERE.md) |
122+
|:---|:---:|---:|

‎concepts/collections-explained.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ items = [item for item in items if item != "remove_me"]
9393
- [Level 1 / 05 Csv First Reader](../projects/level-1/05-csv-first-reader/README.md)
9494
- [Level 1 / 09 Json Settings Loader](../projects/level-1/09-json-settings-loader/README.md)
9595
- [Level 1 / 12 File Extension Counter](../projects/level-1/12-file-extension-counter/README.md)
96-
- [Level 10 / 11 Production Readiness Director](../projects/level-10/11-production-readiness-director/README.md)
96+
- [Level 1 / 14 Basic Expense Tracker](../projects/level-1/14-basic-expense-tracker/README.md)
9797
- [Level 2 / 01 Dictionary Lookup Service](../projects/level-2/01-dictionary-lookup-service/README.md)
9898
- [Level 2 / 02 Nested Data Flattener](../projects/level-2/02-nested-data-flattener/README.md)
9999

‎concepts/errors-and-debugging.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -89,16 +89,14 @@ if True:
8989

9090
## Practice This
9191

92+
- [Level 00 / 08 Making Decisions](../projects/level-00-absolute-beginner/08-making-decisions/)
93+
- [Level 00 / 15 Putting It Together](../projects/level-00-absolute-beginner/15-putting-it-together/)
94+
- [Level 0 / 07 First File Reader](../projects/level-0/07-first-file-reader/README.md)
9295
- [Level 1 / 01 Input Validator Lab](../projects/level-1/01-input-validator-lab/README.md)
96+
- [Level 1 / 08 Path Exists Checker](../projects/level-1/08-path-exists-checker/README.md)
9397
- [Level 1 / 11 Command Dispatcher](../projects/level-1/11-command-dispatcher/README.md)
94-
- [Level 10 / 01 Enterprise Python Blueprint](../projects/level-10/01-enterprise-python-blueprint/README.md)
95-
- [Level 10 / 02 Autonomous Run Orchestrator](../projects/level-10/02-autonomous-run-orchestrator/README.md)
96-
- [Level 10 / 03 Policy As Code Validator](../projects/level-10/03-policy-as-code-validator/README.md)
97-
- [Level 10 / 04 Multi Tenant Data Guard](../projects/level-10/04-multi-tenant-data-guard/README.md)
98-
- [Level 10 / 05 Compliance Evidence Builder](../projects/level-10/05-compliance-evidence-builder/README.md)
99-
- [Level 10 / 06 Resilience Chaos Workbench](../projects/level-10/06-resilience-chaos-workbench/README.md)
100-
- [Level 10 / 07 High Risk Change Gate](../projects/level-10/07-high-risk-change-gate/README.md)
101-
- [Level 10 / 08 Zero Downtime Migration Lab](../projects/level-10/08-zero-downtime-migration-lab/README.md)
98+
- [Level 2 / 04 Error Safe Divider](../projects/level-2/04-error-safe-divider/README.md)
99+
- [Level 2 / 11 Retry Loop Practice](../projects/level-2/11-retry-loop-practice/README.md)
102100

103101
**Quick check:** [Take the quiz](quizzes/errors-and-debugging-quiz.py)
104102

‎concepts/files-and-paths.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ path = Path("C:/Users/alice/new_file.txt") # Forward slashes work too
105105

106106
## Practice This
107107

108-
- [Module: Elite Track / 05 Performance Profiler Workbench](../projects/elite-track/05-performance-profiler-workbench/README.md)
108+
- [Level 00 / 14 Reading Files](../projects/level-00-absolute-beginner/14-reading-files/)
109109
- [Level 0 / 01 Terminal Hello Lab](../projects/level-0/01-terminal-hello-lab/README.md)
110110
- [Level 0 / 02 Calculator Basics](../projects/level-0/02-calculator-basics/README.md)
111111
- [Level 0 / 03 Temperature Converter](../projects/level-0/03-temperature-converter/README.md)

0 commit comments

Comments
 (0)