README Standards¶

Status: 🟢 Active | Owner: Engineering Enablement

Required Sections¶

Every repository must have a README.md in the root containing:

# Service Name

One-sentence description of what this service does and why it exists.

## Overview

2–3 paragraphs covering:
- Business purpose
- Key capabilities
- Where it fits in the architecture (link to architecture diagram)

## Getting Started

### Prerequisites
List all tools and versions required to run locally.

### Local Setup
Step-by-step commands to get the service running locally:
\`\`\`bash
git clone ...
cd service-name
cp .env.example .env
docker compose up -d    # Start dependencies
./gradlew bootRun       # Start service
\`\`\`

## Running Tests
\`\`\`bash
./gradlew test                  # Unit tests
./gradlew integrationTest       # Integration tests
npx playwright test             # E2E tests
\`\`\`

## Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | PostgreSQL connection string | — | Yes |
| `KAFKA_BROKER` | Kafka bootstrap server | localhost:9092 | Yes |

## Architecture

Link to [Architecture Decision Records](docs/adr/) and diagrams.

## API Documentation

Link to OpenAPI spec or Swagger UI URL.

## Deployment

Link to the deployment runbook.

## Contributing

Link to [contribution guidelines](../getting-started/contribution.md).

## Ownership

**Team:** Order Platform Team
**Slack:** #team-orders
**PagerDuty:** Order Service
**Runbook:** [Link]

Freshness¶

READMEs must be updated as part of any PR that changes local setup, configuration, or architecture. A stale README is flagged in the production readiness review.

Last reviewed: 2025-Q4 | Owner: Engineering Enablement

README Ownership and Responsibility¶

The squad that owns the service owns its README. When ownership transfers, an accurate and complete README is a handover prerequisite — the incoming team must be able to set up the service locally and understand its architecture using only the README and the linked documentation, without asking the previous team.

Required Updates That Trigger a README Revision¶

A PR must include a README update when any of the following changes:

Local setup prerequisites or steps
Environment variable names, descriptions, or required values
Test commands or test environment setup
Architecture (new service dependencies, removed components, topology changes)
Deployment process or deployment target
Team ownership details (squad name, Slack channel, PagerDuty service)

"Documentation updated" in the PR checklist means the README has been reviewed and updated, not merely that it was looked at.

README Anti-Patterns¶

Anti-Pattern	Why It Fails
"Run `make dev` to start" with no explanation of what that does	The on-call engineer from another squad cannot debug a failing `make dev`
Configuration table with empty "Description" columns	Provides no guidance on valid values or consequences of misconfiguration
Architecture section that describes how the service used to work	Misleads engineers about the current system; builds wrong mental models
Ownership section pointing to a disbanded squad or departed engineer	Incidents escalate to the wrong person
"See Confluence for details" with a dead link	Confluence pages move; the README is the durable source

Last reviewed: 2025-Q4 | Owner: Engineering Enablement