Skip to content

Lesson Template

Every lesson in this course uses the same fourteen elements in the same order. This page is the authoring standard: copy the skeleton, replace the bracketed text, and delete the guidance notes.

Why a fixed structure

A predictable shape lets a self-learner move through a lesson without wondering what comes next, and lets a reviewer see instantly when something is missing. Consistency is not decoration — it is what makes independent study possible.

The fourteen elements

# Element Where it goes
1 Lesson title The # heading
2 Learning objectives ## Learning objectives
3 Prerequisites ## Prerequisites
4 Introduction ## Introduction
5 Concept explanations ## 1. …, ## 2. … (two or more)
6 Terminology ## Key terms (table)
7 Real-world software examples Inside concept sections, as !!! example blocks
8 Step-by-step worked example ## Worked example
9 Diagrams and tables Inside any section, using Mermaid and Markdown tables
10 Common misconceptions ## Common misconceptions
11 Practical activity ## Practical activity
12 Self-assessment questions ## Self-assessment (answers hidden, one applied scenario)
13 Summary ## Summary
14 Further learning ## Further learning

A ## Next section is optional at the end.

Skeleton

# Lesson N — [Title in sentence case]

!!! info "At a glance"
    - **Module:** [NN — Module name]
    - **Level:** [Beginner | Intermediate | Advanced]
    - **Estimated time:** [NN minutes]
    - **Example project:** [Which of the [example projects](../course-content/example-projects.md) this lesson uses]

## Learning objectives

By the end of this lesson you should be able to:

1. [Observable verb — explain, apply, construct, evaluate, justify…]
2. [Objective]
3. [Objective]

## Prerequisites

- [What must already be understood, with a link to the lesson or module]

## Introduction

[Two or three paragraphs. Why this matters, and what question the lesson answers. Do not define
everything here — that is what the concept sections are for.]

---

## 1. [First concept]

[Explain in plain language before any application. Introduce each term as you need it.]

!!! example "[Example project]"
    [Apply the concept to one of the example projects. Say explicitly that it is illustrative.]

[Use a table or a Mermaid diagram if it genuinely clarifies something a paragraph could not.]

## 2. [Second concept]

[Continue. Aim for two to five concept sections per lesson.]

---

## Key terms

| Term | Meaning |
| --- | --- |
| **[Term]** | [One-sentence definition as used in this course] |

## Worked example

[Number the steps. Show the arithmetic or the decisions, not just the result. Label any invented
figures as illustrative.]

1. **[Step]:** [What you do, and why you do it that way]
2. **[Step]:** [Continue]
3. **[Step]:** [State the result and what it means]

## Common misconceptions

!!! warning "“[The misconception]”"
    [Why it is wrong or incomplete, and what to think instead.]

## Practical activity

[One task, with a clear deliverable. Reference a template if one exists, and say what "good"
looks like.]

## Self-assessment

1. [Question requiring reasoning]
2. [Question]
3. [Question]
4. **Apply it — [example project].** [A concrete situation with a decision to make: what would
   you do, what do you choose, what do you tell whom, and on what basis? Give real numbers and
   name the project.]

    *Hint: [What a strong answer must contain — the criterion it should name, the trade-off it
    should state. Never the answer itself.]*

??? note "Show answers"
    1. [Answer with a brief justification]
    2. [Answer]
    3. [Answer — with model reasoning, not just a conclusion]
    4. [The model answer: name the criterion, apply it to the stated numbers, and state what
       would change the decision.]

## Summary

- [The one-sentence takeaway from each concept section]
- [Takeaway]
- [Takeaway]

## Further learning

- [Internal link to the next related lesson or module]
- [A real, verifiable external source — see Standards & Further Reading. Never invent one.]

---

## Next

[What to read or do next, with a relative link.]

Authoring rules

  • Explain before applying. A student must be able to follow the lesson without an instructor. If a term appears before it is defined, fix the order.
  • Objectives must be observable. "Understand X" is not checkable; "explain why X" is.
  • Label every example. Use !!! example and name the example project. State that the scenario is illustrative.
  • Hide every answer behind ??? note "Show answers" so the student tries first.
  • Apply the technique once. Questions 1–3 test reasoning about the concept; the final item must put the student in a situation — an example project, a number, a decision — because that is what the labs and the capstone require. Mark it **Apply it — …** and give it a visible *Hint: …* line naming what a strong answer contains, so the question scaffolds rather than only testing. check-lessons.py fails a lesson without it, and fails a question whose answer is missing.
  • Prefer Mermaid over images. Diagrams must be readable in the repository and in a diff.
  • Include a comparison table wherever two approaches have real trade-offs, and do not claim one always wins. Say what each is good for and what it costs.
  • Never invent a source. Further learning links to real, verifiable material only. If you cannot verify it, omit it.
  • One idea per lesson. If a lesson needs more than five concept sections, split it.

Adding a lesson to the site

  1. Create docs/course-content/<NN-module>/lessons/<NN-slug>.md.
  2. Add it to nav in mkdocs.yml — a page that is not in the navigation fails the build.
  3. Add it to the lesson plan table on the module's overview page.
  4. Run python tools/check-lessons.py and python tools/validate-structure.py.