Skip to main content

Lesson Style Guide

This guide defines how lessons should be written so the reading experience remains consistent, calm, and architecturally focused.

Headings and structure​

  • Use H1 only for page title (handled by Docusaurus).
  • H2 for major sections: What this lesson covers, Core concept, Why it matters, Design patterns and trade-offs, Common mistakes, What comes next.
  • H3 for subpoints inside sections. Avoid H4+.

Paragraphs and sentences​

  • Paragraphs: 1–3 sentences (20–45 words).
  • Sentences: concise, active voice; average 12–20 words. Use longer sentences only for complex reasoning.

Tone and voice​

  • Calm and instructional: write like a senior engineer teaching another engineer.
  • Avoid hype, urgency, or promotional language.
  • Use neutral, precise vocabulary.

Vocabulary and phrasing rules​

  • Prefer technical clarity: latency, throughput, cold start, idempotency, eventual consistency.
  • Avoid marketing words: do not use best, ultimate, master, crush, or emojis.
  • When introducing an acronym, spell it out once: "Event Sourcing (ES)".

Examples and code​

  • Keep examples short (6–12 lines).
  • Use inline code for parameters (memory, timeout, concurrency).
  • Examples are illustrative; do not claim they are production-ready.

Tables and matrices​

  • Use small decision matrices (2–4 rows, 3–4 columns).
  • Prefer bulleted trade-off lists over large tables when possible.

Accessibility and inclusion​

  • Avoid idioms that may confuse non-native English readers.
  • Prefer clear wording and full terms on first use.

Review checklist (for contributors)​

  • Starts with a Core concept section.
  • Includes Why it matters and Common mistakes.
  • Shows at most two short multi-cloud examples (AWS and GCP).
  • No promotional language, no certification claims.

Use this guide as the canonical reference when authoring or reviewing lessons.