Engineering Practices
Most production outages are not caused by a lack of tooling. They are caused by a change nobody reviewed carefully, a design decision nobody wrote down, a debt item nobody prioritized, or an on-call engineer nobody prepared. The deployment pipelines, monitoring, and alerting elsewhere in this section only work when the people operating them share habits for reviewing, deciding, documenting, and learning.
This section covers those habits. None of them require new infrastructure. All of them compound: a team that reviews well, writes decisions down, and runs blameless postmortems gets measurably faster every quarter, while a team that skips them gets slower in ways that are hard to see until a senior engineer leaves.
Why It Exists
Engineering practices solve three recurring problems:
| Problem | What it looks like | Practices that address it |
|---|---|---|
| Knowledge concentration | Only one person understands the billing service; their vacation is a risk | Code review, pairing, ADRs, technical writing |
| Decision amnesia | "Why did we choose this?" has no answer six months later | Design docs, RFCs, ADRs |
| Repeated failure | The same class of incident happens every quarter | Postmortems, on-call handbooks, tech debt management |
| Unscalable leadership | Every hard technical call routes through one manager | Technical leadership, RFC review processes |
| Inconsistent hiring | Interview outcomes depend on which panel you got | Structured interviewing, rubrics, calibration |
How the Practices Fit Together
The practices form a loop. Writing comes before building, review happens during building, and learning happens after things break — which feeds back into what gets written and prioritized next.
flowchart LR
subgraph Decide["Decide"]
RFC[RFC<br/>org-wide proposals]
DD[Design doc<br/>team implementation plan]
ADR[ADR<br/>record the decision]
end
subgraph Build["Build"]
CR[Code review]
PAIR[Pairing]
TD[Tech debt<br/>management]
end
subgraph Operate["Operate & Learn"]
OC[On-call]
PM[Postmortems]
end
subgraph People["People & Influence"]
TW[Technical writing]
TL[Technical leadership]
HI[Hiring]
OS[Open source]
end
RFC --> DD --> ADR --> CR
PAIR --> CR
CR --> OC
OC --> PM
PM -->|action items| TD
PM -->|new decisions| ADR
TD -->|large paydowns| RFC
TW -.->|underpins| Decide
TL -.->|drives| Decide
HI -.->|grows| Build
The Pages
Decision-Making and Documentation
These four pages are a family. Use the right one for the size and audience of the decision:
| Document | Audience | Scope | Lifespan |
|---|---|---|---|
| RFC | Whole engineering org | Cross-team, significant change | Until decided, then archived |
| Design doc | Your team | Implementation plan for one project | Through delivery |
| ADR | Future engineers | One architectural decision | Permanent, immutable once accepted |
| Technical writing | Everyone | The craft behind all three | — |
RFC Template & Guide — An RFC is a structured proposal for a significant technical change that needs organizational buy-in before anyone writes code. The page explains what deserves an RFC (cross-team impact, new infrastructure, hard-to-reverse choices) and what does not, provides a ten-section template from summary through rollout plan and success metrics, and walks through a complete worked example of migrating internal services from REST to gRPC. It closes with the review process — who reviews, how long comments stay open, how disagreements get resolved — and how to record the final decision.
Read this when: You are proposing a change that affects other teams, introduces new infrastructure, or would be expensive to reverse.
Design Document Template — Where an RFC asks "should we do this?", a design doc answers "how will our team build it?". The page covers when a design doc pays for itself, a template built around problem statement, goals, explicit non-goals, proposed design, alternatives, risks, milestones, and testing strategy, and a full real-world example for adding real-time notifications to a platform. A review checklist at the end helps reviewers catch missing failure modes and unclear scope before implementation starts.
Read this when: Your team is about to start a project longer than a week or two, or one with non-obvious failure modes.
Architecture Decision Records (ADRs) — ADRs capture the why behind a single architectural decision in one or two pages: context, the decision, alternatives considered, and accepted consequences. The page covers the ADR lifecycle (proposed, accepted, deprecated, superseded), numbering and repository organization, tooling such as adr-tools and Log4brains, and several real examples. It also explains when not to write an ADR, so the log stays a signal rather than a chore.
Read this when: You just made a decision a future engineer will question, or you keep re-litigating the same choice in meetings.
Technical Writing for Engineers — The craft that makes every other document on this list effective. It surveys the forms of engineering writing — RFCs, design docs, ADRs, READMEs, documentation — and gives principles for each: lead with the conclusion, write for the reader's context, prefer concrete examples over abstractions. It includes guidance on diagrams and visual communication, a README template, and documentation strategy for keeping docs alive as code changes.
Read this when: Your docs and proposals get skimmed, misread, or ignored.
Code Quality and Collaboration
Code Review Best Practices — Code review is primarily a knowledge-sharing and design-alignment practice; catching bugs is a side benefit. The page covers what to look for, in priority order (correctness, design, security, reliability, readability, style), why small PRs and fast turnaround matter more than thoroughness on huge diffs, how to phrase feedback so it lands (and how to receive it without ego), and which checks to automate so humans focus on judgment calls. It summarizes Google's review guidelines and ends with a sample team review agreement you can adopt directly.
Read this when: PRs sit unreviewed for days, reviews feel adversarial, or approvals have become rubber stamps.
Pairing and mob programming do not have a dedicated page, but they belong here because they are code review moved earlier: two engineers reviewing a design in real time rather than one reviewing a finished diff hours later. Pairing is most valuable for onboarding, for gnarly debugging, and for code with a high cost of mistakes (migrations, auth, billing). Rotate pairs so knowledge spreads, keep sessions to 60-90 minute blocks, and treat a paired change as already reviewed for knowledge-sharing purposes while still running the automated checks described in the code review page.
Tech Debt Management — Technical debt is the implied cost of future rework from choosing expediency today. The page uses Fowler's quadrant (deliberate vs inadvertent, reckless vs prudent) to classify debt, shows how to identify it through code-quality metrics and churn-and-complexity hotspot analysis, how to quantify it in terms leadership understands. It covers prioritization frameworks, a template for pitching a debt paydown, incremental refactoring strategies such as the strangler fig and branch-by-abstraction, and practices that prevent new debt from accumulating.
Read this when: Feature estimates keep growing, or you need leadership to fund a refactor.
Operations and Learning
On-Call Handbook — A practical definition of good on-call: responsibilities during a shift, a structured incident response process, escalation paths, and communication templates for status updates. It includes a blameless post-incident review format, on-call health practices (load limits, compensation, follow-the-sun rotations), a handoff template, PagerDuty/OpsGenie integration examples, and an on-call maturity model. For the alerting side of on-call, pair it with On-Call Best Practices and Escalation Policies.
Read this when: You are joining a rotation, designing one, or your rotation is burning people out.
Postmortem Template & Guide — Postmortems turn an incident into a permanent improvement instead of a recurring cost. The page explains blameless culture and why it produces more honest timelines, provides a complete template (summary, impact, timeline, root cause, trigger, detection, response, contributing factors, action items), and walks through a real example of database connection pool exhaustion. It covers how to write action items that actually get done, how to run the review meeting, and how to build a culture where people volunteer to write postmortems. The incident-process view lives in Postmortem Framework.
Read this when: An incident just ended, or the same kind of incident keeps happening.
People, Leadership, and Community
Technical Leadership Without Management — A guide to the Staff, Principal, and Distinguished engineer track as a parallel path to management. It describes the four common Staff archetypes (tech lead, architect, solver, right hand), how to build influence through a written technical vision and strategy documents, how to lead without authority through alignment and sponsorship, and how to navigate ambiguity when nobody hands you a well-defined problem. It ends with building a technical roadmap, managing your time at senior levels, and common failure modes.
Read this when: You are moving into a Staff+ role, or you need to drive change across teams you do not manage.
Hiring: How to Interview Others — Most engineers are pulled onto interview panels without training. This page covers designing an interview loop that tests distinct signals, writing questions that predict job performance, rubrics and scorecards that make evaluations comparable, techniques for reducing bias, calibration sessions for interviewers, and running the debrief or hiring committee. It also covers selling candidates on the role, and lists interview anti-patterns to retire.
Read this when: You have been added to an interview panel or are designing a hiring loop.
Open Source Engineering — Open source as a strategic engineering practice rather than charity. The page covers how to make a first contribution that maintainers will accept, how to maintain your own project without burning out, a license comparison (MIT, Apache 2.0, GPL, AGPL, BSL) with implications for commercial use, building a contributor community, and monetization models including sponsorships, dual licensing, and open core. It also covers metrics for open source project health and common mistakes.
Read this when: You want to contribute upstream, release an internal tool, or choose a license.
Where to Start
Pick the path that matches your current role or your team's most pressing pain.
Path 1: New to a Team (Individual Contributor)
| Order | Page | Why |
|---|---|---|
| 1 | Code Review Best Practices | You will review and be reviewed in your first week |
| 2 | Technical Writing | Clear PR descriptions and docs build trust fast |
| 3 | Design Document Template | Your first non-trivial project should start with one |
| 4 | On-Call Handbook | Prepare before your first shift, not during it |
| 5 | Postmortem Template | Read a few past postmortems to learn the system's failure modes |
Path 2: Tech Lead or Senior Engineer
| Order | Page | Why |
|---|---|---|
| 1 | RFC Template | Drive cross-team changes through written proposals |
| 2 | ADRs | Start a decision log for your team's services |
| 3 | Tech Debt Management | Make the case for paydown in business terms |
| 4 | Hiring | You will be running interview loops |
| 5 | Technical Leadership | Grow influence beyond your immediate team |
Path 3: Team in Firefighting Mode
If incidents keep recurring and the backlog only grows, start here:
flowchart LR
A[Postmortem Template<br/>learn from each incident] --> B[On-Call Handbook<br/>stabilize response]
B --> C[Tech Debt Management<br/>prioritize the causes]
C --> D[ADRs<br/>record what you changed and why]
Start With One Practice, Not All of Them
Adopting eleven practices at once guarantees none of them stick. Pick the one that addresses your team's loudest pain, run it for a quarter, and only then add the next. For most teams that first practice is either faster code review or consistent postmortems.
Signs a Practice Is Working
| Practice | Healthy signal | Warning sign |
|---|---|---|
| Code review | Median time to first review < 4 business hours; PRs mostly < 400 lines | Rubber-stamp approvals; PRs waiting days |
| Design docs / RFCs | Major projects start with a doc; reviewers find issues before code | Docs written after the fact to justify decisions |
| ADRs | New engineers find answers to "why" questions in the log | Log abandoned after the first ten entries |
| Tech debt | A fixed share of capacity goes to debt each cycle | Debt work only happens after incidents |
| Postmortems | Action items close within their due date; repeat incidents fall | Postmortems blame individuals or never get written |
| On-call | Pages per shift low and actionable; people volunteer for rotation | Engineers dread on-call or leave over it |
| Hiring | Interviewer scores agree in calibration; offer acceptance stable | Decisions hinge on one loud interviewer |
Practices Decay Into Ceremony
Every practice on this page can become a box-ticking exercise: postmortems nobody reads, ADRs written for compliance, reviews that only check formatting. Revisit each practice yearly and ask whether it still changes outcomes. If it does not, fix it or drop it.
Practices by Team Size
Not every practice pays off at every size. Formal process introduced too early slows a small team down; introduced too late, a large team drowns in tribal knowledge.
| Team size | Essential | Add when it hurts | Usually overkill |
|---|---|---|---|
| 1-5 engineers | Code review, lightweight postmortems | ADRs for the few big decisions | Formal RFC process, hiring committees |
| 5-20 engineers | Code review agreement, design docs, on-call rotation, postmortem template | ADR log, tech debt budget | Multi-stage RFC review boards |
| 20-100 engineers | All of the above, RFCs for cross-team changes, structured interviews | Staff+ roles with explicit scope | — |
| 100+ engineers | Everything, plus an RFC review cadence, interviewer calibration, a technical strategy owned by Staff+ engineers | Open source program office | — |
War Story (illustrative)
A 12-person startup copied a large company's RFC process wholesale: every change touching more than one service needed a written RFC and a two-week comment period. Within a quarter, engineers started splitting changes artificially to stay under the threshold, and the RFC queue held more documents than the team could read. They replaced it with a one-page design doc for anything taking more than a week, reviewed in a 30-minute meeting, and reserved RFCs for decisions affecting the whole company. Throughput recovered within a month, and the design docs turned out to be the more useful archive.
Common Anti-Patterns
| Anti-pattern | What happens | Better approach |
|---|---|---|
| Review as gatekeeping | Senior engineers block PRs over style preferences | Automate style; reserve review comments for design and correctness |
| Doc-after-code | Design docs written to justify what was already built | Make a reviewed design doc a precondition for starting multi-week work |
| Blame-flavored postmortems | "Engineer X forgot to..." in the root cause | Ask what made the mistake easy; fix the system, not the person |
| Debt as a separate backlog | Debt tickets live in a list nobody grooms | Allocate a fixed share of each cycle, tied to measurable outcomes |
| Hero on-call | One person handles most incidents because they know the most | Pair junior engineers on shifts; turn hero knowledge into runbooks and ADRs |
| Unwritten leadership | Technical direction lives in one person's head | Publish a written technical vision and keep it current |
| Gut-feel hiring | Each interviewer asks whatever they like | Shared question bank, rubrics, and calibration sessions |
Practices and Delivery Metrics
The four DORA metrics are the most widely used way to measure delivery performance. Engineering practices move them more than tooling does:
| DORA metric | Practices that move it | Mechanism |
|---|---|---|
| Deployment frequency | Code review (small PRs), pairing | Small, quickly reviewed changes ship more often |
| Lead time for changes | Code review speed, design docs | Fewer review round-trips; design problems found before coding |
| Change failure rate | Code review, ADRs, tech debt management | Fewer misunderstood designs; less fragile code to change |
| Time to restore service | On-call handbook, postmortems, runbooks | Prepared responders; recurring failure modes already documented |
Track these alongside the practice-specific signals above. If a practice is adopted but none of these move over two or three quarters, it is probably being done as ceremony.
Related Sections
- Incident Response — the process view of handling incidents end to end
- Alerting — designing the pages that on-call engineers respond to
- SRE — error budgets and toil reduction that inform tech debt priorities
- Runbooks — operational procedures that complement the on-call handbook
- Developer Experience — measuring how practices and tooling affect engineering velocity
Key Takeaways
- Engineering practices are the human systems that make technical systems reliable; they compound over time.
- Use RFCs for org-wide proposals, design docs for team implementation plans, and ADRs to record decisions permanently.
- Code review and pairing are knowledge-sharing practices first and bug-catching practices second.
- Postmortems, on-call, and tech debt management form a loop: incidents produce action items that become prioritized debt work.
- Adopt one practice at a time, measure whether it changes outcomes, and prune practices that have become ceremony.