Skip to content

Pedagogy

Jump to bottom
jkmpod edited this page Mar 11, 2026 · 1 revision

Pedagogy

This page documents the teaching and learning principles applied in the Code to Cloud tutorial.

The core problem being solved

Novice developers typically encounter cloud deployment as a wall of documentation — reference material written for people who already understand the system. The result is that beginners either follow a tutorial mechanically without building a mental model, or give up entirely.

This tutorial is designed to solve a specific version of that problem: a developer who can write code but has never deployed anything, and needs to understand why each step exists before they can apply it reliably.

Pedagogical principles

1. Analogical scaffolding

Every new concept is introduced through an analogy to something the learner already understands. This is the most prominent structural decision in the tutorial — the concept tables in every chapter are not glossaries, they are bridges.

New concept Familiar anchor
Repository A project folder with superpowers
Commit A save point with a sticky note
Branch A parallel universe to experiment in
Docker image A pre-baked cake
Container The cake being served
Dockerfile A recipe

This approach is grounded in Ausubel's assimilation theory — new knowledge is retained when it can be anchored to existing cognitive structures. For a learner with no DevOps background, abstract definitions of "immutable artifact" or "container runtime" are inert; concrete analogies give them somewhere to attach.

2. Worked examples over abstract description

Throughout the tutorial, concepts are demonstrated through concrete, runnable examples rather than described in the abstract. The Git chapter does not say "commits record changes" — it shows a terminal session with actual commands, realistic file names, and real output.

This reflects the distinction between declarative knowledge (knowing that something is true) and procedural knowledge (knowing how to do it). The tutorial targets procedural knowledge — the learner should be able to open a terminal and reproduce every step shown.

3. Sequential ordering that mirrors a real workflow

The chapters are not ordered by complexity or by convention — they are ordered by the sequence in which a developer actually encounters each concept when deploying a real application for the first time:

write code → version control → containerise → understand the network → deploy → automate → verify

This mirrors situated learning — knowledge is more transferable when it is acquired in the context where it will be used, in the order it will be needed.

4. Reducing extraneous cognitive load

Several design decisions exist specifically to reduce extraneous cognitive load — mental effort spent on the format of the material rather than the content itself:

  • Step wizards — the Git and Docker chapters use tabbed step-by-step wizards rather than presenting all commands at once. A learner reads one step, executes it, then advances. This mirrors how an expert would teach the same content in person.
  • Progressive disclosure — callouts (info, warning, danger) are used to surface the most important constraint at the moment it is relevant, not at the start of the chapter.
  • Visual rhythm — alternating section backgrounds, consistent spacing, and the single-accent-colour palette reduce the visual decision-making burden, leaving more attention for the content.

5. Explicit error prevention

Rather than waiting for learners to make mistakes and then correcting them, the tutorial front-loads the most common errors as prominent danger callouts at the moment of highest risk:

  • Never commit directly to main — shown before the first commit step
  • Never tag Docker images as :latest in production — shown during the build step
  • Never put database passwords in docker-compose.yml — shown in the Compose chapter
  • Never expose your database port to the public internet — shown in the Networking chapter

This reflects error-avoidance pedagogy — for novices, preventing a mistake is more efficient than correcting it after the fact, because mistakes at this level often require significant debugging time and erode confidence.

6. Multiple modalities per chapter

Each chapter provides the same core content in three forms:

  1. Written explanation — concept tables, prose, callouts
  2. Worked example — terminal sessions, code blocks, YAML files
  3. Video — an embedded YouTube video covering the same topic

This reflects dual coding theory (Paivio) — information encoded through both verbal and visual channels is retained more effectively than information encoded through one channel alone. Learners who prefer to read can skip the video; learners who prefer to watch can skip the prose; the checklist at the end requires engagement regardless of how the content was consumed.

What the tutorial does not attempt

  • Comprehensiveness — this is a first mental model, not a reference. It covers the minimum viable conceptual surface area. Depth is deferred to the linked external resources.
  • Assessment — there are no quizzes or exercises. The interactive checklist in Chapter 08 is the only active recall element, and it is practical rather than evaluative.
  • Adaptive pacing — the tutorial is linear. A learner who already understands Git can scroll past Chapter 02; there is no gating or branching.

These are constraints accepted in service of simplicity — both for the learner and for the maintainers of the tutorial.

Clone this wiki locally