From 4f2dec27cc8d4f7f56d7a13df724e442af940743 Mon Sep 17 00:00:00 2001 From: razorblade23 <81590614+razorblade23@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:13:18 +0200 Subject: [PATCH 1/4] Updated documentation on contributing, lesson guidelines, etc... --- CONTRIBUTING.md | 53 +++++------------------- LESSON_GUIDELINES.md | 41 ++++++++++++++----- README.md | 2 +- ROADMAP.md | 78 +++++++++++++++++++++--------------- templates/lesson-template.md | 13 ++++-- 5 files changed, 95 insertions(+), 92 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2879dd..081557f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,58 +8,23 @@ To keep things simple, we use a Two-Repo System: * The Ledger (This Repo): Contains only Markdown files. * The Engine: A separate repository that handles the website and the Python interpreter. -You do not need to know `React` or `JavaScript` to contribute here. You only need to know `Markdown` and `Python`. Its also a good idea to visit **Docusaurus** documentation as this is our rendering engine which has some additional markdown elements which you can use. +You do not need to know `React` or `JavaScript` to contribute here. You only need to know `Markdown` and `Python`. ## 🛠️ How to Contribute -1. Fix a Typo or Bug +* Fix a Typo or Bug If you see a mistake in a lesson: 1. Click the "Edit this page" button at the bottom of the lesson on the website. 2. This will take you directly to the file on GitHub. 3. Make your changes and submit a Pull Request (PR). -2. Propose a New Lesson or Project +* Propose a New Lesson or Project If you want to add a new section to the curriculum: - 1. Open an Issue first to discuss the scope. - 2. Fork this repository. - 3. Create a new .md file in the appropriate folder (e.g., 01-foundations/). - 4. Follow the Lesson Structure below. - 5. Submit a PR for review. - -## 📝 Lesson Structure -> **Interactive Sandbox:** Use the `interactive` tag > to provide a live editor if you want to do so. -> ``` -> ```python interactive -> # Provide starter code here -> print("Try changing this!") -> ``` -> ``` -> Our engine will provide the student with code editor and runnable python interpreter right there in the browser. - -Every lesson should follow this relativly short format to ensure consistency: - -1. **Front Matter:** Every file must start with: -``` - --- - id: lesson-slug - title: Human Readable Title - sidebar_position: X - sidebar_label: X. Introduction - --- -``` -> If the document you are writing is a **lesson**, be sure to **tag** it as such by adding `lesson: true` to front matter. -> ``` -> lesson: true -> ``` - -2. **Theory:** A concise explanation of the concept (2–3 paragraphs max) - -3. **The Challenge:** A small task the student must complete to prove they understood the concept. - -## 🐍 Style Guide -* **Tone:** Encouraging, professional, and clear. Avoid overly academic jargon. -* **Python Version:** All code examples must be compatible with Python 3.10+. -* **Code Style:** Follow PEP 8 standards. Use 4 spaces for indentation. -* **Simplicity:** If a concept can be explained with a cat analogy instead of a mathematical proof, choose the cat. + 1. Open [Curriculum Roadmap](/ROADMAP.md) to see what lessons need to be worked on. + 2. Open an **Issue** first to discuss the scope. + 3. Fork this repository. + 4. Create a new `.md` file in the appropriate folder (e.g., 01-foundations/). + 5. Follow the [Lesson Guidelines](/LESSON_GUIDELINES.md) document to structure your lesson to confront with the project. + 6. Submit a PR for review. ## 🚦 Pull Request Process * Ensure your Markdown is valid and links are not broken. diff --git a/LESSON_GUIDELINES.md b/LESSON_GUIDELINES.md index d2119da..3cd795f 100644 --- a/LESSON_GUIDELINES.md +++ b/LESSON_GUIDELINES.md @@ -1,16 +1,35 @@ -### 🏗️ Required Lesson Structure -Every markdown file must contain these exact sections in order: - 1. **Front Matter:** Standard YAML metadata (id, title, sidebar_label, sidebar_position). - 2. **Introduction (The "Why"):** Hook the student with a real-world problem or pain point before providing the code solution. - 3. **Learning Outcomes:** A concrete, bulleted list of what they will confidently understand/do by the end. - 4. **Conceptual Overview:** High-level architectural logic. Explain why do we use the specific concept and explain the basics behind the idea of a concept. Keep it simple and concise. - 5. **Assignments:** 2-3 links to high-quality external resources (Official Docs, Real Python, PEPs). **This is mandatory** - **Make sure the links provided actually resolve to real resources** - 6. **Knowledge Checks:** Deep-dive questions they *must* be able to answer before moving on. Do not answer these in the text; force them to find them in the assignments. - 7. **🏆 The Ledger Challenge:** An interactive practice task using our python interactive code block. Provide a template, minimal starter code, and a "Documentation Hunting Tip" hint. - 8. **Next Steps:** A 1-2 sentence conceptual bridge to the next lesson. +# 📝 Lesson Structure +Lessons should always follow the same structure. You can use [Lesson Template](/templates/lesson-template.md) to quickly scaffold skeleton of your lesson. +1. **Front Matter** - we use front matter to organize our lessons. Some of the tags are required and some of them are optional. + * `id`(**required**) - identifier for the lesson. Keep it short and with no spaces (use `-` for replacing space) + * `title` (**required**) - human readable title to be shown at the top of the lesson + * `sidebar_label` (**required**) - human readable label on the sidebar + * `sidebar_position` (**required**) - position of the lesson in the respective directory + * `lesson` (**optional**) - marks the document as a lesson, enabling tracking of progress, and providing *Mark as Complete* button at the end of the lesson. + * `isDraft` (**optional**) - marks the lesson as *Work in Progress / Draft* and displays the warning on the lesson (but still visible on the live page) +2. **Introduction (The "Why"):** Hook the student with a real-world problem or pain point before providing the code solution. +3. **Learning Outcomes:** A concrete, bulleted list of what they will confidently understand/do by the end. +4. **Conceptual Overview:** High-level architectural logic. Explain why do we use the specific concept and explain the basics behind the idea of a concept. Keep it simple and concise. +5. **Lesson Content:** Provide the basic examples and mention basics of using the related subject. Do not list every possible function / method as the point is to focus students on learning to search for solutions and reading documentation rather then spoon feeding them. +6. **Learn More section:** Use our *custom admonition* to point students to documentation or well written articles. Learn how to use it below. Make sure you give them exact directions on what to focus on, rather then letting them get lost in rabbit hole. For example provide a link to external resource and say: `Read thrue sections 1.3 to 1.6` to learn about list comprehension. +7. **Check Knowlege section:** A set of questions student should be able to answer after finishing with the lesson (and documentation hunting). Be sure to include questions that are not mentioned in the lesson body so students must search documentation to find the answer. +8. **Exercise Section:** Content of the lesson (including documentation hunting) should be distilled into a meaningful exercise, that students will solve on their own machines. **Do not provide interactive editor for this section.** Exercises are test based (`pytest`) and are done with "levels" (by using `@pytest.mark.skip` decorater on all tests execpt the first one). See the [repository](https://github.com/ThePythonLedger/python-exercises) to learn more about writing exercises. When submitting a lesson, you must also submit an exercise that follows it. +9. **Assigment Section:** Assigment is also a required section, but unlike exercises, assigments follow a storyline from the start of the lessons - `simple-python-shop`. Students are encouraged to build and modify their existing project, following the lessons. **Do not provide interactive editor for this section.** Students complete this step on their own machines. +10. **What's Next section:** A 1-2 sentence conceptual bridge to the next lesson. -### ⚠️ Guidelines & What to Watch Out For +### Useful Features to Use +In addition to [standard markdown](https://www.markdownguide.org/) and [Docusaurus markdown](https://docusaurus.io/docs/markdown-features) we have a few custom built components. +* **Interactive python interpreter** - an interactive browser-based python interpreter (built with **Skulpt**) provides instant running of python code right there in the browser, reducing context switching and providing instant feedback on the code. This is intended for bringing code examples to life but should not be used for exercises or assigments which are to be done on local machine. All you need to do is to add `interactive` to your code blocks ans it takes care of the rest. + ``` + ```python interactive + print("Hello World!") + ``` + ``` + +* **Custom *Learn More* admonition** - in addition to Docusaurus provided admonitions, we have implemented a custom one for *Learn More* section. To create such admonition, use standard Docusaurus syntax with `explore` keyword. + +## ⚠️ Guidelines & What to Watch Out For * **❌ Don't list every method.** Do not give a table of every string or list method. Give them one example, then send them to the official docs to discover the rest. * **✅ Accurate Mental Models.** Avoid overly childish analogies, but also avoid assuming knowledge the student doesn't have yet. Don't reach for systems-level concepts like threads, processes, or execution contexts — a beginner has no scaffolding for these. Instead, build correct foundational models they *can* understand. Accuracy means not teaching things that will need to be "un-taught" later, not front-loading advanced vocabulary. Keep it simple, concise and provide links to external documentation and articles. * **❌ No Spoilers.** Do not provide answers to the Knowledge Checks in the lesson body. diff --git a/README.md b/README.md index 47cff8c..f9b730a 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Inspired by the philosophy of *The Odin Project*, we believe the best way to lea * **Local Development Enviroment:** Real developers use their local machines to build and tests software. This is exactly how we are going to start. Locally, on your own machine. -* **Interactive Lessons:** We use `Skulp` engine to render interactive python code blocks. If your code block has `interactive` tag, our engine will render it as runnable python code - directly in the browser. +* **Interactive Lessons:** We use `Skulp` engine to render interactive python code blocks. If your code block has `interactive` tag, our engine will render it as runnable python code - directly in the browser. This helps students retaing knowlege and see the code in actuon, right there in the browser - no context switching. This should only be used to explain the concepts in the lessons and not for **exercises** or **assigments**. * **Curriculum-as-Code:** This entire resource lives on GitHub. If a lesson is unclear or a link is broken, the students are encouraged to fix it themselves. diff --git a/ROADMAP.md b/ROADMAP.md index f6afe74..9f01df4 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,37 +1,51 @@ # Current curriculum plan This may be subject to change. +## Legend +`[ ]` - no work has been done +`[-]` - somebody is working on this but it has not yet been completed. There should be a related PR. +`[x]` - lesson completed + +## Roadmap 1. Introduction * [x] How course works? - * [x] CS Basics - * [x] What is a programming language? - -2. Foundations - * [x] What is Python? - * [ ] Local Development Enviroment (WIP) - * Command Prompt - * Downloading & Installing Python - * VS Code - * `git` and **Github** - * REPL vs *script files* - * [x] Foundations (web based) - * print() - * Variables - * Data types - * Math - * Comparisons - * [ ] Conditionals & Loops (web based) - * If/elif/else - * match/case - * for and while loops - * enumerate() - * zip() - * break / continue - * for-else pattern - * [ ] Functions - * Functions - * `*args`/`**kwargs` - * Mutable argument trap - * LGBT scope rules - * [ ] Mini - Project 1 - * Terminal guessing game? \ No newline at end of file + * [x] Motivation and Mindset + * [ ] Asking for help + * [ ] Join the Community + * [x] Computers and Programming Languages (CS Basics) +2. Prerequisites + * [x] Installation of required software + * [x] Text Editor basics + * [x] Command Line basics + * [x] Python - What is it? REPL vs Scripts +3. Git Basics + * [x] Introduction to Git + * [x] Setting up Git and Github + * [x] Git basics +4. Python Foundations + * [x] Output (print), Variables, Core Datatypes + * [x] Math, String operations, Comparisons + * [x] User input, Conditionals + * [x] Loops + * [-] Data Structures + * [-] List + * [-] Tuple + * [-] Set + * [-] Dictionary + * [ ] Functions + * [ ] Project 1 +5. Modules, Working with Files and Error Handling + * [ ] Working with multiple files (`__init.py__`, directory structure, etc...) + * [ ] Opening, Closing and Manipulating files + * [ ] Error Handling (`try-except-else-finally`) + * [ ] Custom Exceptions + * [ ] Defensive Coding patterns + * [ ] Working with structured data (`json`, `csv`, etc...) + * [ ] Project 2 +6. OOP, Virtual Environments and third party libraries, Working with APIs + * [ ] Classes and OOP + * [ ] Usage and setup of virtual environments + * [ ] Installation of third party libraries + * [ ] Working with APIs + * [ ] Project 3 - *probably: * weather app +7. Working on Projects, Solving bugs, Reading errors \ No newline at end of file diff --git a/templates/lesson-template.md b/templates/lesson-template.md index 0142bb8..a277422 100644 --- a/templates/lesson-template.md +++ b/templates/lesson-template.md @@ -7,21 +7,26 @@ lesson: true isDraft: true --- # Lesson Title -## Introduction {#introduction} ## Lesson Overview {#overview} +## Concept Overview -## Lesson Content +### Lesson Content -## Assignment {#assignment} +:::explore +Documentation Hunting +::: + +## Answer These Questions -## Deepen Your Knowlege {#learn-more} +## Exercise +## Assignment {#assignment} ## What's Next {#next-lesson} \ No newline at end of file From 63e90d77959f1c0835454c6ffa0fc1e2e9cb189e Mon Sep 17 00:00:00 2001 From: razorblade23 <81590614+razorblade23@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:18:18 +0200 Subject: [PATCH 2/4] Added a section about AI usage --- LESSON_GUIDELINES.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/LESSON_GUIDELINES.md b/LESSON_GUIDELINES.md index 3cd795f..61e015c 100644 --- a/LESSON_GUIDELINES.md +++ b/LESSON_GUIDELINES.md @@ -29,6 +29,9 @@ In addition to [standard markdown](https://www.markdownguide.org/) and [Docusaur * **Custom *Learn More* admonition** - in addition to Docusaurus provided admonitions, we have implemented a custom one for *Learn More* section. To create such admonition, use standard Docusaurus syntax with `explore` keyword. +## ⚠️ No AI in lesson content +We strongly belive that human written content has way more value and can teach a lot more then AI generated content can, so please do not use AI to write the content. If you do not have the time or knowlege, do not use AI as it will be rejected. + ## ⚠️ Guidelines & What to Watch Out For * **❌ Don't list every method.** Do not give a table of every string or list method. Give them one example, then send them to the official docs to discover the rest. * **✅ Accurate Mental Models.** Avoid overly childish analogies, but also avoid assuming knowledge the student doesn't have yet. Don't reach for systems-level concepts like threads, processes, or execution contexts — a beginner has no scaffolding for these. Instead, build correct foundational models they *can* understand. Accuracy means not teaching things that will need to be "un-taught" later, not front-loading advanced vocabulary. Keep it simple, concise and provide links to external documentation and articles. From 39de1d7c9e943baa034742ca82c830a10164f10c Mon Sep 17 00:00:00 2001 From: razorblade23 <81590614+razorblade23@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:32:06 +0200 Subject: [PATCH 3/4] Fixed PR instructions --- CONTRIBUTING.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 081557f..ddf6ee0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,11 +23,14 @@ If you want to add a new section to the curriculum: 2. Open an **Issue** first to discuss the scope. 3. Fork this repository. 4. Create a new `.md` file in the appropriate folder (e.g., 01-foundations/). - 5. Follow the [Lesson Guidelines](/LESSON_GUIDELINES.md) document to structure your lesson to confront with the project. - 6. Submit a PR for review. + 5. Follow the [Lesson Guidelines](/LESSON_GUIDELINES.md) document to structure your lesson to confront with the project lessons. + 6. Submit a **draft PR** for so we can label the lesson as *Being Worked On* as soon as you have some content. Our pipeline will check your document for inconsistencies automaticly even in draft PRs. ## 🚦 Pull Request Process +* * +* Submit a **draft PR** as soon as possible so somebody else does not do double work. * Ensure your Markdown is valid and links are not broken. +* When your changes are complete, submit a PR. * Your PR will be reviewed by a maintainer. * Once merged, the Engine will automatically detect the changes and rebuild the live site within minutes. From 1b8d721f6b26284cd7e97aeae0746da15746d491 Mon Sep 17 00:00:00 2001 From: razorblade23 <81590614+razorblade23@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:34:05 +0200 Subject: [PATCH 4/4] Fixed a typo --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddf6ee0..5bb8d38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,6 @@ If you want to add a new section to the curriculum: 6. Submit a **draft PR** for so we can label the lesson as *Being Worked On* as soon as you have some content. Our pipeline will check your document for inconsistencies automaticly even in draft PRs. ## 🚦 Pull Request Process -* * * Submit a **draft PR** as soon as possible so somebody else does not do double work. * Ensure your Markdown is valid and links are not broken. * When your changes are complete, submit a PR.