Skip to content

Design‐Philosophy

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

Design Philosophy

This page documents the visual and structural design decisions behind the Code to Cloud tutorial.

Aesthetic direction

The tutorial uses a clean editorial aesthetic, deliberately modelled on long-form digital publications rather than typical developer documentation or slide decks. The reference point was Github-101 — a scrollytelling explainer that makes technical concepts approachable through layout and pacing rather than density.

The key choices that define this aesthetic:

Typography

  • Fraunces (serif) for headings — an expressive, high-contrast typeface that gives the tutorial a considered, editorial feel distinct from generic developer tools
  • Plus Jakarta Sans for body copy — clean and readable at small sizes without being generic
  • JetBrains Mono for all code, terminal output, labels, and metadata — reinforces the developer context wherever it appears

Colour

  • A single accent colour: GCP blue (#1a73e8) — contextually meaningful for the audience and consistent with the platform being taught
  • Supporting semantic colours: green for success/go, amber for warnings, red for danger — used only in callouts and tags, never decoratively
  • Off-white background (#f8f8fc) with alternating sections in a slightly deeper tone — creates rhythm without visual noise

Layout

  • Maximum content width of 740px — wide enough for tables and code blocks, narrow enough to feel like a document rather than a dashboard
  • Generous vertical padding between sections — each chapter feels like a distinct unit, not a continuous scroll of undifferentiated content

Structural decisions

Single-file architecture

The entire tutorial is one HTML file (index.html). No JavaScript framework, no CSS preprocessor, no build pipeline. This was chosen for three reasons:

  1. The audience is novice developers — a complicated repo structure would undermine the tutorial's own message about keeping things simple
  2. GitHub Pages can serve it with zero configuration
  3. The tutorial teaches containerisation and deployment; it should not itself require a complex deployment

Sectioned chapters, not pages

Rather than separate HTML pages per chapter, the tutorial uses full-viewport sections within a single scrollable page. This was inspired by the scrollytelling format of the reference — the reader's progress through the page mirrors their conceptual progress through the material.

Progressive disclosure via wizards and tabs

Several chapters (Git workflow, Docker workflow) use a step-by-step wizard pattern rather than presenting all terminal commands at once. This reflects a core principle: show the learner only what they need at each moment. A novice who sees fifteen terminal commands at once will skip them; a novice who sees one command per step will read each one.

Interactive elements

Element Used in Purpose
Step wizard Git (Ch02), Docker (Ch04), Compose (Ch04b) Sequences multi-step workflows without overwhelming
Concept table All chapters Anchors new vocabulary to familiar analogies
Compare columns Commits (Ch03) Makes the contrast between good and bad practice visceral
Network layer diagram Networking (Ch05) Visualises an abstract stack as a concrete list
Pipeline diagram Why (Ch01), CI/CD (Ch07) Shows the full journey at a glance
Interactive checklist Ch08 Converts passive reading into active verification
Embedded video All chapters Provides an alternative learning modality per topic
Resource links All chapters Extends the tutorial without expanding its scope

What was deliberately left out

  • Dark mode — the editorial aesthetic depends on the white-and-ink palette; a dark mode toggle would add complexity without meaningful benefit for this audience
  • Search — the tutorial is linear by design; search implies reference documentation, which is a different genre
  • Authentication or persistence — the checklist state resets on page reload; this is intentional, it is a pre-flight check, not a progress tracker
  • Mobile-first layout — the tutorial is designed for a developer at a laptop, not a phone; responsive adjustments exist but they are not the primary target

Clone this wiki locally