On this page

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:

ProblemWhat it looks likePractices that address it
Knowledge concentrationOnly one person understands the billing service; their vacation is a riskCode review, pairing, ADRs, technical writing
Decision amnesia"Why did we choose this?" has no answer six months laterDesign docs, RFCs, ADRs
Repeated failureThe same class of incident happens every quarterPostmortems, on-call handbooks, tech debt management
Unscalable leadershipEvery hard technical call routes through one managerTechnical leadership, RFC review processes
Inconsistent hiringInterview outcomes depend on which panel you gotStructured 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:

DocumentAudienceScopeLifespan
RFCWhole engineering orgCross-team, significant changeUntil decided, then archived
Design docYour teamImplementation plan for one projectThrough delivery
ADRFuture engineersOne architectural decisionPermanent, immutable once accepted
Technical writingEveryoneThe 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)

OrderPageWhy
1Code Review Best PracticesYou will review and be reviewed in your first week
2Technical WritingClear PR descriptions and docs build trust fast
3Design Document TemplateYour first non-trivial project should start with one
4On-Call HandbookPrepare before your first shift, not during it
5Postmortem TemplateRead a few past postmortems to learn the system's failure modes

Path 2: Tech Lead or Senior Engineer

OrderPageWhy
1RFC TemplateDrive cross-team changes through written proposals
2ADRsStart a decision log for your team's services
3Tech Debt ManagementMake the case for paydown in business terms
4HiringYou will be running interview loops
5Technical LeadershipGrow 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

PracticeHealthy signalWarning sign
Code reviewMedian time to first review < 4 business hours; PRs mostly < 400 linesRubber-stamp approvals; PRs waiting days
Design docs / RFCsMajor projects start with a doc; reviewers find issues before codeDocs written after the fact to justify decisions
ADRsNew engineers find answers to "why" questions in the logLog abandoned after the first ten entries
Tech debtA fixed share of capacity goes to debt each cycleDebt work only happens after incidents
PostmortemsAction items close within their due date; repeat incidents fallPostmortems blame individuals or never get written
On-callPages per shift low and actionable; people volunteer for rotationEngineers dread on-call or leave over it
HiringInterviewer scores agree in calibration; offer acceptance stableDecisions 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 sizeEssentialAdd when it hurtsUsually overkill
1-5 engineersCode review, lightweight postmortemsADRs for the few big decisionsFormal RFC process, hiring committees
5-20 engineersCode review agreement, design docs, on-call rotation, postmortem templateADR log, tech debt budgetMulti-stage RFC review boards
20-100 engineersAll of the above, RFCs for cross-team changes, structured interviewsStaff+ roles with explicit scope—
100+ engineersEverything, plus an RFC review cadence, interviewer calibration, a technical strategy owned by Staff+ engineersOpen 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-patternWhat happensBetter approach
Review as gatekeepingSenior engineers block PRs over style preferencesAutomate style; reserve review comments for design and correctness
Doc-after-codeDesign docs written to justify what was already builtMake a reviewed design doc a precondition for starting multi-week work
Blame-flavored postmortems"Engineer X forgot to..." in the root causeAsk what made the mistake easy; fix the system, not the person
Debt as a separate backlogDebt tickets live in a list nobody groomsAllocate a fixed share of each cycle, tied to measurable outcomes
Hero on-callOne person handles most incidents because they know the mostPair junior engineers on shifts; turn hero knowledge into runbooks and ADRs
Unwritten leadershipTechnical direction lives in one person's headPublish a written technical vision and keep it current
Gut-feel hiringEach interviewer asks whatever they likeShared 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 metricPractices that move itMechanism
Deployment frequencyCode review (small PRs), pairingSmall, quickly reviewed changes ship more often
Lead time for changesCode review speed, design docsFewer review round-trips; design problems found before coding
Change failure rateCode review, ADRs, tech debt managementFewer misunderstood designs; less fragile code to change
Time to restore serviceOn-call handbook, postmortems, runbooksPrepared 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.

  • 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.