# Examples — Technical Documentation House Style

# Contents

Complete worked example: README (bad → house style)
ADR mini-pattern examples
Runbook entry (bad → house style)
Scannability conversions
Gotchas

# Complete worked example: README

❌ Before (typical drifted README):

markdown

# payment-router

Welcome to payment-router! This repository contains the source code for the
payment routing system. Payment routing is an important part of our
infrastructure. It is a robust, scalable, high-performance solution.

## Background

Historically, payments were processed by the monolith. In 2023 the team
decided to extract routing. There were many discussions about the
architecture. Kafka was considered...

(three more screens before any command)

✅ After (house style):

markdown

# payment-router

Routes card transactions to the cheapest eligible processor. Used by the
checkout service — most engineers only need the client library below.

## Quickstart

    pip install payment-router-client

    from payment_router import route
    decision = route(amount_cents=1999, currency="USD", card_bin="424242")
    print(decision.processor)  # "stripe"

## How it works

Each transaction is scored against processor fee tables (refreshed hourly)
and eligibility rules (`rules/*.yaml`). Highest-margin eligible processor
wins. Ties break on historical auth rate.

## Why SQS, not Kafka

Context: volume is under 100 msg/s and we already run on AWS.
Decision: SQS for retry queues.
Consequences: no replay; revisit if volume exceeds 1,000 msg/s.

## Configuration

| Variable | Default | Effect |
|---|---|---|
| `PR_FEE_REFRESH_MIN` | `60` | Minutes between fee-table refreshes |
| `PR_FALLBACK` | `stripe` | Processor when no rule matches |

## Operations

Benchmarks (as of 2026-08): 2,000 req/s on one c7g.large, p99 = 11 ms.
Runbook: [docs/runbook.md](docs/runbook.md)

What changed: purpose + audience in two sentences; runnable quickstart in the first screen; decision documented with its why; config as a table; verifiable numbers with a date stamp; zero marketing adjectives.

# ADR mini-pattern examples

✅ "Context: we need per-tenant encryption and already use KMS. Decision: one KMS key per tenant, cached data keys (5 min TTL). Consequences: +$1/tenant/month; key deletion gives crypto-shredding for free."

❌ "The system encrypts data per tenant using KMS." (decision with no why — the next engineer re-litigates it from scratch)

# Runbook entry (bad → house style)

❌ Before: "If the queue backs up, investigate the consumers and restart if needed."

✅ After:

markdown

## Symptom: `router_queue_depth > 10k` alert

1. Diagnose: `kubectl logs deploy/router-consumer --since=10m | grep ERROR`
   - `FeeTableStale` → refresh job failed, go to step 2
   - `ProcessorTimeout` → upstream incident, escalate to #payments-oncall
2. Fix: `kubectl create job --from=cronjob/fee-refresh manual-refresh`
3. Verify: queue depth falling within 5 minutes.
4. Escalate: if still rising after 15 min, page payments-primary.

# Scannability conversions

Enumerable prose → table, always:

❌ "The service supports three modes. In strict mode it rejects unknown fields. In lenient mode it ignores them. In log mode it accepts them but logs a warning."

✅

Mode	Unknown fields
`strict`	rejected (400)
`lenient`	ignored
`log`	accepted, warning logged

# Gotchas

Untested code blocks are the #1 trust killer — a quickstart that errors on line one discredits the whole doc. Run every command before committing.
"Simply" and "just" hide missing steps; delete them and add the step.
Architecture docs that describe the aspiration, not the system as built: mark aspirational sections explicitly ("Planned, not implemented").
Screenshots rot fastest of all; prefer text output, and date-stamp any screenshot you must include.
Duplicated content between README and wiki always diverges; pick one home and link from the other.