Engineering Handbook: Team Norms, Decision Frameworks, and Communication Standards

An engineering handbook is not an HR policy manual. It's the document that answers the questions new engineers ask in week two: "How do we decide what to build?" "Is it okay to push directly to main?" "Who reviews security-sensitive PRs?" "Do I need to be in every standup?"

Good handbooks are written by the team, not the leadership. They reflect how work actually happens, not how it should happen ideally.

---

What Belongs in an Engineering Handbook

Not everything — a handbook that covers everything is never read. Focus on the questions that come up repeatedly:

# Engineering Handbook

## 1. How We Work
  - Team principles
  - Decision-making framework
  - Async-first communication

2. Code

• Coding standards (link to .eslintrc, Prettier config)
• Code review process and expectations
• Branch and commit conventions
• Deployment process

3. On-Call and Incidents

• On-call responsibilities
• Incident severity levels (link to runbooks)
• Postmortem process

4. Meetings

• Standing meetings and when to skip
• Meeting-free time blocks
• When a meeting should be a document

5. Career and Growth

• Engineering levels (what each level looks like)
• Feedback cadence (1:1s, reviews)
• How to raise a concern

6. Tools and Access

• How to get access to systems
• Which tools we use and why
• Security policies

---

## Team Principles (Written by the Team)

Principles work when they're specific and actionable. Generic principles ("we value quality") tell you nothing about what to do when quality and speed conflict.

```markdown

Our Engineering Principles

1. Boring technology is usually right

We use established, well-understood tools over new and exciting ones. The question is not "is this technology cool?" but "will this still be maintainable in 3 years with 5 different engineers?"

Implication: adding a new database, framework, or service requires an ADR with explicit justification.

2. Ship it, then improve it

A working feature in production beats a perfect feature in review. We favor small, frequent deployments over large batches.

Implication: PRs should be reviewable in < 30 minutes. If they're longer, split them.

3. Async by default, sync when needed

Most decisions can be made asynchronously. We don't hold discussions hostage to meetings. We write things down.

Implication: If you need a decision from someone, write the context and proposal in Linear/Notion before requesting a meeting.

4. On-call is a team sport

If your code pages someone at 3am, that's a team failure, not an individual one. We write runbooks for known failure modes. We fix the alert, not just the symptom.

Implication: Every PR touching critical paths should ask "does this need a runbook?"

5. Leave it better than you found it

If you touch code that's confusing, undocumented, or has a paper-cut, fix or document it as part of your PR. Small improvements compound.

Implication: "Out of scope" is not an excuse to leave obvious problems unfixed.

---

## Decision-Making Framework

The most common engineering team dysfunction: unclear who decides what, leading to either endless consensus-seeking or decisions that surprise people.

**DACI framework:**

```markdown

How We Make Decisions

We use DACI: Driver, Approver, Contributor, Informed.

Decision size guides who's involved:

Small decisions (affects one component, easily reversible)

• Driver: any engineer
• Approver: any engineer
• No approval required — just do it and mention in standup

Medium decisions (affects multiple systems, hard to reverse)

• Driver: any engineer
• Approver: tech lead or engineering manager
• Write a brief proposal in Slack or Linear thread; get sign-off before building

Large decisions (affects architecture, team practices, or significant cost)

• Driver: tech lead or engineering manager
• Approver: CTO
• Write an ADR; present in architecture review; 1-week comment period

---

## Code Review Standards

```markdown

Code Review Expectations

For PR Authors

• PRs should be reviewable in < 30 minutes (< 400 lines changed ideally)
• Write a description: what, why, and how to test
• Resolve all CI failures before requesting review
• Don't request review during another engineer's focus block (9am-12pm)
• If a PR is urgent (production fix), label it urgent — reviewers respond in 1 hour

For Reviewers

• Respond within 1 business day (not 1 hour — async-first)
• Distinguish between blocking comments and suggestions:
  • Blocking: [BLOCKING] This will cause a race condition...
  • Suggestion: [NIT] Could simplify this to... (author's call whether to act)
• Approve with comments when non-blocking issues remain — don't hold up PRs over style
• If you'd reject a PR, explain why clearly and suggest an alternative

What to Look For (in order of priority)

1. Correctness: Does it do what it says? Does it handle errors and edge cases?
2. Security: Could this introduce a vulnerability?
3. Maintainability: Will the next engineer understand this?
4. Performance: Any obvious bottlenecks?
5. Style: (Leave to linter; don't comment on things ESLint catches)

Automated Checks (CI must pass before merge)

• TypeScript: no type errors
• ESLint: no lint errors
• Tests: no test failures
• Coverage: no reduction in coverage below threshold
• Build: no build errors

---

## Async Communication Standards

Remote and hybrid teams often collapse into one of two failure modes: excessive synchronous communication (too many meetings), or under-communication (decisions made invisibly). The handbook defines the boundary:

```markdown

Communication Channels and When to Use Them

Slack

Use for: Questions, quick updates, time-sensitive coordination Don't use for: Decisions, announcements, anything that needs a record

Response expectation: within 4 hours during business hours. Do not expect immediate responses. @-mention only when urgent.

Linear (task tracker)

Use for: All work that needs doing. Bugs, features, tech debt, improvements. Don't use for: Questions, discussion (use Slack or Notion)

Every PR should be linked to a Linear ticket.

Notion

Use for: Decisions, proposals, meeting notes, documentation Don't use for: Real-time conversation

When a Slack discussion produces a decision, write it in Notion. Link the Notion doc in the Slack thread.

Email

Use for: External communication, formal notices Don't use for: Internal team communication (use Slack)

Meetings

Use for: Relationship-building, complex real-time collaboration, unblocking someone who's stuck Don't use for: Status updates, information broadcasting, decisions that can be made async

Before scheduling a meeting: "Could this be a Notion doc with a 48-hour comment period?" If yes: write the doc instead.

---

## Meeting Culture

```markdown

Standing Meetings

Meeting-Free Blocks

Tuesdays and Thursdays, 9am–12pm: no meetings scheduled by default. Engineers protect this time for deep work. Urgent issues can override; everything else can wait.

Meeting Norms

• Every meeting has an agenda (written 24 hours in advance)
• Every meeting produces a written output: decision, action items, or "discussed and no action needed"
• Meetings end on time. If unfinished, schedule a follow-up — don't overrun.
• Camera optional for remote meetings — you're here to contribute, not perform presence.

---

## Keeping the Handbook Alive

A handbook written in a retreat and never touched is worse than no handbook — it creates false expectations.

```markdown

Handbook Maintenance

This handbook is a living document. It's wrong in some ways right now.

How to update it

Submit a PR. Any engineer can update any section. Tag the relevant team lead as a reviewer. Changes that affect how the whole team works need 48-hour comment period.

Mandatory review triggers

• After any postmortem: update the relevant section if process failed
• After every new engineer's first 30 days: ask them what was missing or wrong
• Quarterly: each section owner reviews and confirms it's current

Section owners

Each section is owned by one person who is responsible for keeping it current. They are not the only person who can edit it — they're the person who notices when it's stale.

---

## Working With Viprasol

We help engineering teams document and improve their processes — writing first versions of engineering handbooks, facilitating team retrospectives, designing decision frameworks, and setting up the tooling (Notion, Linear, ADR templates) that supports the culture.

→ [Talk to our team](/contact) about engineering culture and process design.

---

See Also

• Software Documentation — ADRs, runbooks, and technical docs
• Developer Onboarding — putting the handbook to work on day 1
• Code Review Best Practices — deeper dive into review culture
• Incident Management — on-call norms in detail
• Web Development Services — engineering team advisory