Styleguide

This is the official style guide for How Money Actually Moves. Every chapter must follow these rules. When in doubt, read an existing chapter and match its patterns.

Voice and Tone

  • Conversational but authoritative. Write like a knowledgeable friend explaining payments over coffee, not like a textbook. The reader should feel like they're learning from someone who genuinely finds this stuff fascinating.
  • Use "you" freely. Address the reader directly. Pull them into scenarios. Make them the protagonist of the payment flow, not a passive observer.
  • Avoid jargon without explanation. When you must use a technical term, define it immediately in plain language. For example: "The acquirer then forwards this request through the card network — Visa, Mastercard, whoever — to the card's issuing bank (the customer's card-issuing bank)."
  • Short sentences are fine. Mix sentence lengths. Don't let paragraphs run past four or five sentences. One-sentence paragraphs can land a point with force.
  • Use analogies and grounding. Payments are abstract — ground concepts in everyday experiences. If you're explaining settlement netting, compare it to splitting a dinner bill. If you're explaining clearing, compare it to filing paperwork before a bank transfer.
  • Take a clear position when the facts support one. Don't hedge everything with "perhaps" or "it could be argued." If settlement typically takes T+2, say so.
  • Show genuine enthusiasm. Italics and emphasis are tools for conveying the writer's excitement about a counterintuitive fact or a clever system design. Use phrases like "here's what's wild" or "something remarkable just happened" to signal moments of revelation.

Structure

Opening Hook

Every chapter must open with a compelling scenario, question, or surprising fact. Never start with a definition. The reader should be pulled in before they know they're learning.

Good example (from Chapter 4):

"Picture this: It's Monday morning, 8:55am. You're running late for your 9am meeting, and you desperately need coffee..."

Bad example:

"Authorization is the first step of a card transaction in which the issuing bank approves or declines..."

Subheadings

Use subheadings generously. A reader should be able to skim the headings and get the gist of the chapter. Subheadings can be questions ("What truly happened when I bought my coffee?") or declarative ("Clearing: Communicating the Transaction Details").

Section Flow

Each major section should follow this pattern:

  1. Hook or transition — Connect from the previous section or pose a question
  2. Core explanation — The meat of the concept, in plain language
  3. Technical detail — Dig deeper for readers who want it (use callouts for truly technical notes)
  4. Risk or implications — What can go wrong? Why does this matter?
  5. Bridge — Connect to the next section or the bigger picture

Ending Each Chapter

Close each chapter by connecting to what comes next. Use a sentence like: "In the next chapter, we'll explore..." This keeps the reader moving through the book.

Running Scenarios

Use a consistent real-world scenario throughout a chapter to anchor abstract concepts. Chapter 4 uses "buying coffee at WhiteBottle Coffee" as the thread. This technique gives the reader a concrete reference point as complexity increases.

Formatting Rules

Headings

  • Use H1 (#) for major chapter sections (e.g., "How does the payment cycle work?")
  • Use H2 (##) for sub-sections within a major section (e.g., "Authorization and Hold")
  • Use H3 (###) for further breakdowns (e.g., "Single and Dual-Message transactions")
  • Never go deeper than H3. If you need more granularity, use bold text or numbered lists.

Bold and Italic

  • Bold key terms on first use. Use sparingly after that.
  • Italics for emphasis, internal monologue, or to highlight a surprising or counterintuitive point. Example: "no money has moved yet. Not a cent."
  • Don't overuse either. If everything is bold, nothing is.

Technical Identifiers

Write technical identifiers as-is, with no special formatting: ISO 8583, PCI DSS, ACH, SWIFT, ISO-20022. These are proper nouns in the payments world and don't need code formatting.

Numbers

  • Spell out one through nine.
  • Use numerals for 10 and above.
  • Always use numerals for money ($5, $1.2 billion) and percentages (3%).
  • For time durations, use numerals with units: 300ms, T+2, 2 seconds.

Tables

Use tables for structured comparisons (e.g., single-message vs. dual-message transactions, network tokens vs. gateway tokens). Tables work well when:

  • Comparing two or more things across multiple dimensions
  • Summarizing stages of a process with consistent attributes (purpose, timing, money movement, etc.)

Keep table cells concise. Don't write full paragraphs inside cells.

Callouts

Use callouts for technical asides that would break the flow of the main narrative. These are for readers who want the engineering-level detail without forcing everyone to read it.

Example pattern:

Technical note — Authorization messages are standardized (for example, using ISO-8583 or similar formats) so that the data can be understood as it travels from the merchant to the issuer.

Diagrams and Images

When referencing a diagram, introduce it with context and tell the reader what to look for. Provide a caption that summarizes the key takeaway. Example: "The only canonical diagram you'll need to understand how cards work!"

Diagram format: All diagrams in the book must use Mermaid syntax inside fenced code blocks tagged as mermaid. Do not use PlantUML, as it does not render natively in Notion. Supported Mermaid diagram types: sequenceDiagram, flowchart / graph, and classDiagram.

Lists

No bullet-point walls. Use prose paragraphs as the primary format. Bullets are fine for short lists (three to seven items) but should not be the backbone of any section.

Numbered lists work well for:

  • Sequential steps in a process (authorization steps 1-4)
  • Ordered concepts (the five functions of money)

Bulleted lists work well for:

  • Non-sequential collections of related points
  • Short enumerations within a larger prose section

Narrative Techniques

The Reveal Pattern

A signature technique of this book: present the simple, visible experience first, then pull back the curtain to show the hidden complexity. Example from Chapter 4:

Simple: You tap your card, hear a beep, see "Approved."

Reveal: In that split second, your card talked to your bank, your bank talked to the coffee shop's bank, multiple fraud checks ran, and money was reserved.

Direct Address and Rhetorical Questions

Speak directly to the reader. Use rhetorical questions to create engagement: "But here's the thing: WhiteBottle hasn't received any money yet. So where did the money go?"

Step-by-Step Narration with Diagram References

When walking through a multi-step process, number each step and include a reference to where the reader can find it on the canonical diagram. Example: "In the diagram: Follow that arrow from the left box to the center: Card Scheme Network."

Foreshadowing

Reference future chapters when a topic will be covered in more depth. This builds anticipation and prevents the current chapter from becoming too long. Example: "We'll dig into these scenarios — partial approvals, auth-capture mismatches, and the bank's risk logic — in Chapter 7."

What to Avoid

  • Academic tone or passive voice. Not: "It can be observed that settlement occurs on T+2." Yes: "Settlement usually happens on T+2."
  • Filler phrases. Cut these ruthlessly: "It's important to note that...", "In today's world...", "As we all know...", "It goes without saying..."
  • Overly long introductions. Get to the substance quickly. The hook should be short and punchy, not a full page of setup.
  • Fabricated content. Never make up statistics, quotes, or case studies that aren't in the source research. If the research doesn't support a claim, don't make it.
  • Unsourced surprising claims. If a claim feels surprising or counterintuitive, attribute it. Example: "According to the Federal Reserve's 2023 payments study..."
  • Footnotes or academic citations. Weave sources into the narrative naturally. Use inline links or parenthetical references, not superscript numbers.
  • Over-hedging. Don't qualify every statement. If the evidence supports a claim, state it directly.

Citations and Sources

When the research includes specific data points, company examples, or statistics, reference them naturally in the text. Examples:

  • "Visa processes around 65,000 transactions per second."
  • "Babylonian temples routinely lent grain and silver at interest — often around 33% per annum on grain loans and 20% on silver loans."

For direct quotes from researchers or historians, attribute them with the person's name and context. Example: "As historian Yuval Harari observed, 'Money is the most universal system of mutual trust ever devised by humans.'"

Include a Sources section at the end of each chapter listing the key references used. Use inline links rather than footnote-style numbering.

Chapter Length and Pacing

  • Default target: 2,000 to 3,000 words per chapter, unless the Linear ticket specifies otherwise.
  • Longer chapters (like Chapter 4 at ~5,000+ words) are acceptable when the topic demands it, but break them into clearly scannable sections.
  • Every 500-800 words, give the reader a moment to breathe — a new subheading, a transition, or a short summary before diving deeper.

Consistency Across Chapters

  • Use the same terminology throughout the book. If you call it an "issuing bank" in one chapter, don't switch to "issuer bank" in another. Preferred terms:
    • Issuing bank (or issuer) — the bank that issued the cardholder's card
    • Acquiring bank (or acquirer) — the merchant's bank
    • Card network (or card scheme) — Visa, Mastercard, etc.
    • Authorization — not "authorisation" (use American English throughout)
  • Use American English spelling consistently: authorize, not authorise; check, not cheque (unless referring to the historical instrument).
  • When referencing other chapters, use the format: "As we covered in Chapter 2..." or "We'll explore this further in Chapter 7."

Interactive apps (web edition)

A code block whose first line is app:<name> embeds a micro interactive app at that point in the page. The web edition renders the live app; print/PDF and EPUB replace it with a short placeholder. The code block's language doesn't matter — only the content.

Lines after the first may hold a JSON object that configures the app (used by compare-table).

Available apps:

  • payment-flow — step-through animation of the canonical $100 card payment (auth → capture → clearing → settlement). Used in Chapter 4.
  • settlement-timeline — pick sale day / cutoff / payout speed and see when cash actually lands. Used in Chapter 4.
  • fee-calculator — interchange++ fee-stack explorer (card type × region × amount). Used in Chapter 10.
  • threeds-simulator — 3DS frictionless vs challenge decision paths, exemptions and liability shift. Used in Chapter 11.
  • chargeback-lifecycle — choose-your-path dispute state machine with money-position tracking. Used in Chapter 13.
  • dunning-simulator — retry-strategy recovery curves over 30 days. Used in Chapter 15.
  • routing-simulator — orchestration strategies (single PSP / least-cost / highest-auth / cascade) over simulated traffic. Used in Chapter 32.
  • compare-table — generic sortable/filterable comparison table driven entirely by the JSON config. Used in Chapters 3, 8, 18, 22 and Appendix C.
  • flow-animation — config-driven animated flow diagram. The code block content is app:flow-animation plus a JSON line like {"preset": "four-party"}. Available presets: four-party, auth-clearing-settlement, qr-scan, direct-debit, vault-tokenize, orchestration-failover, trusted-ledger, closed-loop, carrier-billing, stablecoin-card, stored-credential, agentic-payment, correspondent-chain, gateway-psp, metered-billing, risk-pipeline. Used in Chapters 2, 3, 5, 6, 9, 16, 17, 19, 20, 21, 22, 25, 26, 29, 31, 33 and Appendix B.
  • bnpl-split — one order through Pay-in-4 / 0% financing / interest-bearing plans: consumer schedule, merchant fee vs cards, provider unit economics. Used in Chapter 23.
  • token-flow — what each hop (customer → merchant → PSP → network → issuer) stores in a raw-PAN vs network-token world, with a merchant-breach simulation. Used in Chapter 12.
  • remittance-race — the same transfer over wire / cash pickup / fintech / stablecoin rails: what arrives, what it costs, how fast. Used in Chapter 28.
  • timeline — config-driven chronological timeline: milestones on a vertical rail with expandable detail, a group filter, and a table-view toggle. The code block content is app:timeline plus a JSON line like {"preset": "diners-to-defi"}. Available presets: diners-to-defi, rtp-links, bnpl-regulation, payments-changelog, payments-deadlines. Also accepts a full inline config: {"title": "...", "items": [{"date": "1950", "label": "...", "detail": "...", "group": "..."}]} — items render in authored order, dates are free-form strings. Prefer this over a Mermaid flowchart or gantt for any chronological milestone sequence. Used in Chapters 7, 18, 23 and 40.

Example:

Loading interactive…

An unknown app name renders as a subtle "isn't available yet" note on the web (and nothing breaks), so blocks can be authored before the app ships.

The Money Atlas — Styleguide