Last March, an engineer on my client’s platform team got paged at 2:47 AM. The webhook delivery service was retrying a backlog of 40,000 events into a downstream payments API that had started rejecting requests with 429s. The on-call engineer—a capable mid-level developer who’d been on the team for four months—spent the first forty minutes not debugging the problem. He was reconstructing what had happened the last time this occurred.

Three weeks earlier, there had been a post-mortem for a nearly identical incident. It was technically accurate. Listed the timeline, the root cause (a missing circuit breaker on the retry queue), and the action items. But it read like a stream-of-consciousness brain dump. The timeline jumped between the webhook service and the payments API without signaling the shift. The root cause section referenced RetryQueueWorker and PaymentsClient as if the reader already knew which service owned which. The action items were buried after three paragraphs of internal monologue about what the author thought was happening before they realized it wasn’t.

The on-call engineer eventually figured it out. But by then, the retry backlog had grown to 110,000 events, the downstream payments team had opened their own incident, and the window for a clean rollback had closed. The cost of that post-mortem’s bad structure was forty minutes of reconstruction time and a cascading failure that could have been contained.

I’ve been thinking about this incident for months, and I’ve come to a conclusion that feels slightly embarrassing to state as an engineer: the narrative discipline that professional novelists and screenwriters use maps directly onto the engineering artifacts we depend on for team continuity. Not metaphorically. Practically. The structural problems that make a post-mortem unreadable under pressure are the same problems that make a novel’s middle act feel aimless—unclear point of view, inconsistent voice, scenes that start without establishing where the reader is supposed to be.

The Problem: Engineering Prose Without Structure

Most engineering teams produce a surprising volume of prose per week. An RFC for a new webhook retry policy. An ADR explaining why you chose HMAC-SHA256 over JWT verification for webhook signatures. A post-mortem after the retry queue backed up. Three runbook updates. A dozen commit messages that are supposed to explain why someone changed the idempotency key format from UUID to a composite of client_id + timestamp + nonce.

We treat all of this as throwaway writing. Something you dash off between tickets. And then we act surprised when the on-call engineer at 3 AM can’t reconstruct what happened, or when the new hire spends a week reading ADRs and still can’t explain why the API versioning strategy looks the way it does.

The issue isn’t that engineers can’t write. Most engineers I know write perfectly clear code comments, design docs, and Slack messages when they put their mind to it. The issue is that we don’t apply structural thinking to prose the way we apply it to code. We wouldn’t dream of shipping a function with no clear input contract, no named return type, and three side effects hidden in the middle. But we ship post-mortems with no clear narrative contract, no stated point of view, and critical context buried in paragraph four.

What Professional Writers Know That We Don’t

Professional screenwriters use structural conventions—scene headings, act breaks, consistent formatting—specifically so that other people can extract meaning quickly under production pressure. A scene heading like INT. WEBHOOK SERVICE - 02:47 AM tells the director, the cinematographer, and the actors exactly where they are, when they are, and whose perspective they’re in. The principle is simple: proper structure ensures clarity and ease of production, whether the production is a film set or an on-call rotation.

This is not an artistic luxury. It’s a convention born from the same pressure our on-call engineers face: someone else has to act on this document at 3 AM, under stress, with incomplete context, and they need to know where they are in the story immediately.

The mapping is concrete. Commit messages are scene-level artifacts: they establish a single moment, a single change, a single perspective. ADRs are chapter-level artifacts: they establish a decision within a broader arc, with context that spans multiple scenes. Post-mortems are novel-level artifacts: they have a beginning (the incident), a middle (the investigation), and an end (the resolution and action items), and they require consistent voice and point of view across all three.

Scene-Level: Commit Messages

A commit message is the smallest narrative unit in your codebase. It establishes a single moment: this change, in this file, for this reason. The most common structural failure I see is the commit message that starts with the author’s internal monologue and never establishes the scene.

Here’s a real commit message I pulled from a client’s git history last month:

fix: the thing Priya mentioned in standup

This commit touched 14 files across the webhook delivery service and the SDK generator. The “thing” was a bug where webhook retry headers were being overwritten by the SDK’s default retry logic. The commit message gives the reader no scene heading, no location, no time, and no perspective. Six months from now, when someone is bisecting a regression in webhook delivery behavior, this commit will be a dead end.

A structurally sound commit message follows the same logic as a scene heading: establish the location, establish the actor, establish the action. The subject line is your scene heading. The body is your action description.

Before:

fix: the thing Priya mentioned in standup

After:

fix(webhook-delivery): prevent SDK retry headers from overwriting service-level retry policy

The SDK's default retry logic was setting X-Retry-Count on outgoing
webhook requests, which overwrote the delivery service's own retry
tracking. This caused the delivery service to misinterpret retries
as first-delivery attempts, resulting in duplicate webhooks to
downstream consumers.

Root cause: RetryHeadersInterceptor in the SDK ran after the
service's WebhookDeliveryClient set its own headers. Fixed by
moving the SDK interceptor to run only when X-Retry-Count is
absent.

The after version tells you: where you are (webhook delivery), who the actor is (the SDK retry interceptor), what happened (header overwrite), and why it matters (duplicate webhooks). It’s a scene heading followed by action description. Someone bisecting a regression six months from now can read the subject line alone and know whether this commit is relevant.

Chapter-Level: Architecture Decision Records

An ADR is a chapter in your system’s ongoing narrative. It establishes a decision within a broader arc—the evolution of your architecture—and it needs to provide enough context that a reader who joins the story mid-chapter can still follow what’s happening.

The structural failure I see most often in ADRs is the missing “setting.” The author jumps straight to the decision without establishing the landscape: what services exist, what constraints are in play, what the previous chapter was. It’s the equivalent of starting a chapter in the middle of a conversation without telling the reader who’s in the room.

Here’s the opening of an ADR I reviewed recently, verbatim:

ADR-014: We will use HMAC-SHA256 for webhook signature verification.

Decision: HMAC-SHA256 with SHA-256 hashing. The signing secret will
be provisioned per-consumer via the API key management endpoint.

This ADR is technically complete—it states a decision. But it’s structurally broken. It doesn’t establish what came before (the team was using unverified webhooks), what alternatives were considered (JWT, mutual TLS), or what constraints drove the decision (downstream consumers needed a verification method that didn’t require certificate management). A new engineer reading this ADR six months later knows what was decided but not why, and the why is the only part that matters when you’re trying to decide whether the decision still holds.

A structurally sound ADR follows chapter-level conventions: establish the setting, introduce the conflict, present the decision, and state the consequences. The setting is your current architecture. The conflict is the problem forcing a decision. The decision is your resolution. The consequences are what changes in the next chapter.

A reliable ADR template that I’ve used across three platform teams:

  • Context (setting): What does the system look like today? What services, constraints, and existing decisions are in play?
  • Decision (resolution): What are we doing? State it in one sentence first, then elaborate.
  • Alternatives considered (conflict): What else did we evaluate? Why did we reject each option? Name the specific tradeoff, not a vague “too complex.”
  • Consequences (next chapter): What changes? What new work does this create? What existing code or contracts become deprecated?

The “alternatives considered” section is where most ADRs fail structurally. Authors list alternatives as bullet points without explaining the rejection logic. This is the equivalent of a novel where the antagonist is introduced and then disappears without explanation. The reader—especially the reader who joins mid-story—needs to understand why the other paths were not taken, because that understanding is what tells them whether the current path is still valid.

Novel-Level: Post-Incident Reviews

A post-mortem is the longest-form narrative artifact most engineering teams produce. It has a cast of characters (services, teams, on-call engineers), a setting (production, at a specific time), a conflict (the incident), a rising action (the investigation), a climax (the root cause discovery), and a resolution (the fix and action items). It requires consistent voice, clear point of view, and a structure that guides the reader from confusion to clarity.

Google’s SRE book dedicates an entire chapter to postmortem culture and includes a full example postmortem in its appendix, which reflects the reality that structured post-incident reviews are an established engineering discipline, not an instinct. The SRE community has long recognized that how you write a postmortem matters as much as the technical findings. Yet most teams I consult with treat the postmortem document as a formality—a template to fill out—rather than a narrative that someone else will need to read and act on under pressure.

The post-mortem I described at the beginning of this article had all the right sections: timeline, impact, root cause, action items. But it failed narratively in three specific ways:

1. No consistent point of view. The timeline jumped between the webhook service and the payments API without signaling the shift. The reader had to infer which service was experiencing what. In a novel, this would be like switching between two characters’ perspectives mid-paragraph without a scene break. The fix is simple: each timeline entry should name the service or team whose perspective we’re in.

2. The root cause was buried after the internal monologue. The author wrote three paragraphs about what they initially thought was happening before describing what was actually happening. This is the engineering equivalent of a detective novel where the detective’s wrong theories take up more page space than the actual solution. In a post-mortem, the root cause section should lead with the answer, then provide the investigation path that led there. The investigation path is valuable, but it’s supporting material, not the main plot.

3. The action items had no ownership or temporal structure. They were listed as bullet points with no assignee, no due date, and no priority. In narrative terms, this is a resolution with no stakes—nothing tells the reader what happens next, who’s responsible for it, or when it concludes.

The Narrative Structure Checklist

Here’s the artifact I promised. Use this checklist to review your engineering prose before you ship it. The same structural principles apply across all three levels—scene, chapter, novel—but the specific checks differ. I’ve evolved this checklist over three years of consulting engagements, and it started as a single page of notes I kept in my own engineering notebook at Microsoft. Every item on it comes from a specific failure I’ve either committed myself or watched a capable team commit under deadline pressure.

The checklist works because it forces you to shift from author mode to reader mode at the moment you’re most likely to ship something sloppy: the end of a long writing session when the document feels finished because you understand it. The reader doesn’t have your context. Run through the relevant checklist before you hit publish, and you’ll catch the structural gaps that cost the next reader time.

Commit Message Checklist (Scene-Level)

  • Does the subject line establish the location (service or module)?
  • Does the subject line establish the action (what changed)?
  • Does the body explain why the change was necessary, not just what changed?
  • Would someone reading only the subject line know whether this commit is relevant to their debugging context?
  • If the commit fixes a bug, does it name the root cause, not just the symptom?

ADR Checklist (Chapter-Level)

  • Does the context section establish what the system looks like today, not just what problem you’re solving?
  • Is the decision stated in one sentence before elaboration?
  • Does the alternatives section explain why each option was rejected, with a specific tradeoff named?
  • Does the consequences section describe what changes in the next chapter—new work, deprecations, migrations?
  • Could an engineer who joins the team six months later read this ADR and understand why the decision still holds (or doesn’t)?

Post-Mortem Checklist (Novel-Level)

  • Does the timeline establish whose perspective we’re in for each entry (service, team, or individual)?
  • Does the root cause section lead with the answer, followed by the investigation path?
  • Is the internal monologue (what you initially thought) separated from the factual timeline?
  • Does every action item have an owner, a due date, and a priority?
  • Would an on-call engineer who has never seen this incident be able to understand the system’s behavior from this document alone?
  • Is the impact quantified in terms that matter to the business (requests dropped, users affected, revenue impacted), not just in technical metrics?

Here’s a concrete example of the checklist catching a real problem. Last quarter, I reviewed a post-mortem for a rate-limiting misconfiguration that caused 15 minutes of 503s on a payments webhook endpoint. The draft passed items one through four—the timeline was clean, the root cause led clearly, the monologue was separated, and action items had owners. But it failed item five. The author had written “the rate limiter applied the wrong burst limit” without explaining what a burst limit was, how the rate limiter’s config map worked, or what the correct value should have been. An on-call engineer encountering a similar issue at 3 AM would know that the rate limiter was the culprit but wouldn’t know where to look for the config or what value to set. The checklist caught this gap in review, and the author added a two-sentence explanation of the config map path and the correct burst value. That addition took five minutes to write and would save the next on-call engineer twenty.

When the Drafting Gets Hard

The drafting process matters. Professional writers don’t produce structured first drafts by instinct; they use tools that enforce structural conventions and help them see when the narrative is drifting. When you’re producing this volume of internal documentation, the same drafting and structural problems fiction writers face show up in your engineering artifacts. Some teams I’ve worked with have started using an AI novel writing app like Unsloppy as a drafting tool for longer-form internal documents—not because it writes the post-mortem for you, but because the structural scaffolding it provides for narrative drafts (scene tracking, point-of-view consistency, chapter arc awareness) catches the same drift problems that make engineering prose unreadable under pressure. The bridge is narrow but real: when you’re staring at a blank post-mortem template at 11 PM after a four-hour incident, any tool that helps you maintain structural discipline while you’re exhausted is worth evaluating.

No related posts.