Engineering Handbook Template (Markdown)

# {{Company or team}} engineering handbook

| | |
|---|---|
| **Owner** | {{Name or team}} |
| **Applies to** | {{All engineers / the platform team / contractors too}} |
| **Last reviewed** | {{YYYY-MM-DD}} |
| **Next review** | {{YYYY-MM-DD}} |

*The handbook answers "how do we do things here?". Keep each page short, link to the longer document instead of copying it, and give every page one owner. Delete the hint lines when a section is filled in.*

## Start here

- **What we build and who for:** {{two sentences}}
- **How to get help:** {{channel, person, office hours}}
- **First week:** [{{Onboarding checklist}}]({{link}})
- **How to change this handbook:** open a pull request or edit the page; {{who reviews}}

## How we work

- **Planning rhythm:** {{sprints, cycles or continuous; planning and review days}}
- **Ownership:** {{who owns a service or area; where the list is}} ([{{Service catalog}}]({{link}}))
- **Working agreements:** {{core hours, response times, async-first rules}}
- **Meetings we keep:** {{standup, planning, retro, with the purpose of each}}

## Engineering practices

### Code and branches

- **Branching:** {{trunk-based / feature branches; naming}}
- **Commits and pull requests:** {{size, title format, description template}}

### Code review

- **Who reviews:** {{rules}}
- **Turnaround:** {{expected time}}
- **What reviewers check:** {{correctness, tests, readability, security}}

### Testing

- **What must be tested:** {{...}}
- **Definition of done:** {{checklist}}

### Documentation

- **What we document and where:** {{design docs, runbooks, ADRs, API reference}} ([{{Design doc template}}]({{link}}))

## Shipping

- **Environments:** {{dev, staging, production; who can deploy where}}
- **Pipeline:** {{CI steps, required checks}}
- **Release process:** {{how a change reaches users; cadence}} ([{{Release process}}]({{link}}))
- **Feature flags:** {{when to use them, who removes them, by when}}
- **Release notes:** {{who writes them, where they are published}}

## Running in production

- **On-call:** {{rotation, handover, compensation, escalation}} ([{{On-call guide}}]({{link}}))
- **Severity levels:** {{SEV1 to SEV3 with an example each}}
- **Incident response:** {{roles, channel, status page}} ([{{Incident process}}]({{link}}))
- **Runbooks:** {{where they live; one per alert}} ([{{Runbook index}}]({{link}}))
- **Postmortems:** {{when required, blameless, where stored}}

## Architecture and decisions

- **System overview:** {{diagram and the page that explains it}} ([{{Architecture}}]({{link}}))
- **How we decide:** {{when a design doc is required; who approves}}
- **Decision records:** {{where ADRs live; how to supersede one}}
- **Approved technologies:** {{languages, frameworks, databases; how to propose a new one}}

## Security and access

- **Access requests:** {{how to ask, who approves, how fast}}
- **Secrets:** {{where they are stored; never in the repository}}
- **Reporting a security issue:** {{address or channel}}
- **Dependency and vulnerability policy:** {{...}}

## Tools

| Tool | What it is for | Owner | How to get access |
|---|---|---|---|
| {{Source hosting}} | {{...}} | {{Name}} | {{...}} |
| {{CI/CD}} | {{...}} | {{Name}} | {{...}} |
| {{Monitoring}} | {{...}} | {{Name}} | {{...}} |

## People and growth

- **Levels and expectations:** [{{Career ladder}}]({{link}})
- **One-on-ones and feedback:** {{cadence; template link}}
- **Learning:** {{budget, conference policy, internal talks}}

## Glossary

| Term | Meaning |
|---|---|
| {{Term}} | {{One sentence in the words people use here}} |

## Changelog

| Date | Author | Change |
|---|---|---|
| {{YYYY-MM-DD}} | {{Name}} | First version |