Skip to main content

Authoring guide

Before you write​

Open an issue using the New lesson template first. Two questions decide whether a lesson should exist:

  1. What can the reader do afterwards that they could not do before? If the answer is "understand X", the lesson is not scoped yet. Understanding is not observable; doing is.
  2. Where does it sit in the dependency graph? Every lesson names its prerequisites explicitly. If a proposed lesson has no prerequisites and is not in module 00 or 01, something is wrong with the placement.

A maintainer will agree the module, the ordering prefix and the objectives with you before you write. This is not gatekeeping — it is the step that prevents three people independently writing "Understanding rebase".

Scaffold the file​

pnpm content:new

The generator prompts for module, title, level and duration, then writes a file with valid frontmatter and the standard skeleton, using the next free ordering prefix in that module. Never create a lesson by copying another one: you inherit its id, its last_reviewed date and any mistakes it has.

The lesson skeleton​

Every lesson follows the same eight-part shape. Reviewers check for it, and readers rely on it.

  1. Frontmatter

    Machine-readable metadata. See the frontmatter reference.

  2. `<LessonMeta>` block

    Duration, level, minimum Git version and prerequisite links. Placed immediately after the title, before any prose.

  3. `<Objectives>`

    Three to five observable capabilities, each phrased so that a reader could verify for themselves whether they have it. "Recover a commit deleted by a hard reset" is an objective; "understand the reflog" is not.

  4. The idea

    The concept, in prose, before any command. If a reader stops here, they should still have gained the mental model. This section is what distinguishes this curriculum from the manual pages.

  5. Hands-on

    Commands the reader runs, using <Terminal> for sessions and <CommandBlock> for anatomy. Real output, never paraphrased. Punctuate with <Checkpoint> at every point where divergence would break later steps.

  6. When it goes wrong

    The failure modes specific to this material, and how to recognise them. Most Git material omits this, which is exactly why readers get stuck.

  7. Practice

    One to three <Exercise> blocks with progressive hints and a worked solution, and one or two <Quiz> questions for retrieval practice.

  8. `<KeyTakeaways>` and next steps

    Three to five points, then a link to the next lesson.

Length​

The target is 700–1,600 words. pnpm content:stats reports anything over 2,200 words, which is a signal to split rather than a hard limit.

A lesson that will not fit is usually two lessons: one that builds the model and one that applies it.

Verifying commands​

This is the requirement that gets skipped and the one that causes the most reader pain.

  • Run every command in a fresh repository, not your working checkout.
  • Use a current Git release. State the version you used in git_version when the behaviour is version-sensitive, and mark version-specific claims with <VersionNote>.
  • Paste output verbatim. Truncate with a comment if it is long; never edit it to look tidier. Readers compare their output to yours character by character, and a "cleaned up" sample destroys that.
  • Set last_reviewed to the date you actually ran them.

Prose that survives review​

  • Address the reader as you. Never we, never the passive voice used to avoid choosing.
  • Explain why before how. A command with no motivating problem is reference material, and reference material belongs in module 90.
  • Delete hedges. "Generally", "usually", "it is often the case that" — either the claim is true, or it needs a condition attached, in which case state the condition.
  • Never write "simply", "just", "easy" or "obviously". If it were obvious, the lesson would not exist.

Full rules in the style guide.

Before you open the pull request​

pnpm validate    # frontmatter, structure, assets, internal links
pnpm lint        # markdown, spelling, formatting, JavaScript
pnpm build       # catches broken cross-references and MDX errors

pnpm verify runs all three plus type-checking. It is what CI runs.