The screenshot came back with a problem. Chapter 1's "What the next chapters cover" list had chapters 2 through 4 highlighted and linked. The later chapters were plain text. The course was live, and the inconsistency had reached production.
The reason was mechanical. When I drafted chapter 1, chapters 5 through 8 didn't exist. I'd left those references as plain text because there was nothing to link to yet. When those four chapters shipped, completing the course at 8/8, I didn't go back. The fix was a find-and-replace pass across all eight chapters. Twenty minutes.
The decision that would have prevented it took longer to arrive at than it should have. Inline chapter links should have been an architectural rule from day one. It's one of three architecture calls the course forced before any writing happened. The other two were cleaner.
What the course is
The GSC + GA4 guide is an 8-chapter technical course on automating Google Search Console and Google Analytics 4. It lives on captainrandom.co.uk under the /learning route. Chapters 1 through 3 shipped first. Chapters 5 through 8 landed in a single PR that took the topic from 4/8 published to complete.
Chapter 1 is the motivation layer, 1,500 words on why you'd automate these APIs rather than use the dashboards. Chapter 2 is a full walkthrough of Google Cloud project setup: OAuth screen configuration, service account creation, credential download. It's the chapter that forced the first two decisions.
Decision one: throwaway GCP project per reader
Chapter 2 opens with "create a new Google Cloud project." Not "open your existing project." A throwaway, scoped to the tutorial.
The alternative fails for the same reason it always does in GCP tutorials. Readers in existing projects inherit ambient IAM state: enabled APIs, service accounts with already-granted roles, permissions that may or may not match what the walkthrough expects. Debugging a tutorial failure caused by pre-existing configuration is unresolvable from the author's side.
Billing isolation is the other reason. A fresh project can be deleted at the end of the course. Any accidental API calls, any quota consumed, disappear with it.
The throwaway model costs the reader five minutes at the start. It removes an entire class of support surface. That trade-off is obvious enough that the decision closed in the first session, before chapter 2 was written.
Decision two: Steps components over prose
Chapter 2 is a UI walkthrough. The GCP console is not static. The OAuth configuration screen moved from the old Cloud Console flow to the new Google Auth Platform interface between when the course was planned and when it was built. New fields. Different order. The chapter had to be rewritten to match what's actually in front of a reader who opens GCP today.
Prose can't carry this cleanly. A paragraph that says "click the button on the left, then select the dropdown that reads X, then fill in the field below it" has no spatial anchor for the reader. You need screenshots with numbered steps.
The decision was to build a Steps and Step component pair and use them for all procedural UI sections. Chapter 2 ended up with 13 step screenshots across the project setup and OAuth configuration sections. The capture session was a sit-down with the browser open via the MCP claude-in-chrome extension, working through the flow screen by screen, capturing each state as it appeared.
The component decision had a forward-planning effect too. Once the component exists, you know which chapters need it. Chapter 5 covers the Python CLI shape for Google APIs (around 1,700 words). It's code-heavy and doesn't use Steps. Chapter 2 does. That distinction becomes part of the chapter spec before drafting starts, not something you discover mid-write.
Decision three: inline chapter links from day one
This is the one I didn't make correctly.
Chapters 1 through 3 were drafted first. Chapters 5 through 8 were planned but unwritten at that point. Chapter 1's overview section listed all eight chapters: the standard "here's what we cover" block that helps a reader decide whether to continue or jump ahead. Chapters 2 through 4 had slugs, so I linked them. The later chapters had no slugs yet, so I left them as plain text, intending to update when the chapters shipped.
I didn't update when they shipped. The list in production had linked and unlinked entries mixed, with no visual signal about which chapters existed. I caught it from a chapter 1 screenshot.
The lesson isn't that I should have predicted slugs for chapters that didn't exist yet. It's that "link every chapter reference as soon as the target exists" needs to be an enforced rule, not a drafting-time intention. If the chapter template requires every reference to resolve, a missing link is a build-time catch, not something that reaches production. The repair was a cross-course find-and-replace. It caught every outstanding plain-text reference in one pass.
Out of scope: a remark plugin to lint unresolved chapter references at build time. The course is a fixed set of eight chapters; the overhead isn't justified.
The execution
Two PRs. The first shipped chapters 1 through 3. The second completed the course: chapters 5 through 8 in a single PR, 8/8 live.
Chapter 5 is the architectural centre of the automation work. It defines the shape a Python script takes when consuming any Google API, regardless of which one. That framing comes from the devlog rather than from GSC or GA4 themselves. Establishing the general shape before the specific API calls is the pedagogical decision the chapter rests on.
The three decisions are independent. Throwaway GCP projects have nothing to do with component design. Component design has nothing to do with link conventions. But all three were resolved before the first word of chapter 2 was written. That sequence matters.
What this means for course architecture
An article is self-contained. A course isn't. It has navigation, chapter dependencies, shared UI patterns, and a reader who may arrive at any chapter from search and need orientation. Each of those properties produces a structural constraint. Ignoring the constraint during drafting means paying it back later: a screenshot resession, a component retrofit, or a link-update sweep.
The link debt cost twenty minutes. The Steps debt would have cost considerably more if left to address after prose chapters were written. The 13-screenshot capture works when you know what the UI flow is, and it's harder to retrofit into a chapter designed without visual slots.
Make the structural calls before chapter one. The writing is the easy part.
