Engineering handbook: what to include and maintain

Technical documentation describes what your systems do — API references, architecture diagrams, data models, service READMEs. An engineering handbook describes how your team works — coding standards, development workflows, PR processes, on-call procedures, and decision-making frameworks. Both are essential, but they serve different audiences and purposes. The handbook is primarily for engineers working within the team; technical documentation is for anyone building on or operating your systems.

There is no right length — the handbook should be exactly as long as needed to document your team's practices completely. Small teams (5–15 engineers) typically maintain handbooks of 20–50 pages. Large engineering organisations like GitLab have handbooks spanning thousands of pages. The key is starting with the highest-value sections (onboarding, development standards, deployment process) and growing incrementally. A short, accurate handbook is far more valuable than a comprehensive but outdated one.

The engineering handbook is owned collectively by the engineering organisation, with individual sections assigned to named owners. Typically the Engineering Manager or Director of Engineering owns the overall structure and ensures sections have active owners. Tech leads own architecture and standards sections. DevOps/platform engineers own the CI/CD and deployment sections. On-call leads own the incident response runbooks. The key principle is that every section has a named human responsible for its accuracy — orphaned sections inevitably become outdated.

ADRs are short documents that capture the context, decision, and consequences of significant architectural choices. They explain why systems are built the way they are, preventing future engineers from unknowingly revisiting settled decisions. ADRs should be stored in your code repository (typically in a /docs/adr/ directory) as markdown files so they version alongside the code. The handbook should document the ADR process — how to propose one, the required format, how decisions are ratified, and how to find and read existing ADRs.

The most effective anti-staleness measures are: named section ownership so every part of the handbook has someone accountable; a handbook-first culture where questions are answered by pointing to the handbook (and adding missing answers); quarterly review cycles where section owners audit their content; new joiner feedback loops where every onboarding engineer submits at least one improvement; and surfacing the handbook prominently in PR templates, onboarding tasks, and Slack workflows so it gets used daily. Usage drives maintenance.

GitLab's decision to make their entire handbook public is one of the most celebrated examples of transparency in the industry, and they report significant recruiting and culture benefits from it. For most companies, a hybrid approach works well: make general engineering principles, workflow documentation, and cultural content public (it signals engineering quality to candidates) while keeping security runbooks, incident response procedures, internal tooling details, and anything involving proprietary systems private.

The onboarding section should enable a new engineer to go from zero to productive without interrupting colleagues. It should include: a pre-day-one checklist (accounts to provision, hardware setup); local environment setup steps (with copy-paste commands, not prose descriptions); a first-week task list with clear milestones; an introduction to the team's ways of working (standups, planning, retrospectives); key contacts and when to use each communication channel; links to all relevant tools (GitHub, Jira, Slack, monitoring); and a list of the most important architectural concepts to learn in the first two weeks.

The best tool depends on your team's preferences and existing stack. Git-based options (MkDocs, Docusaurus, or GitLab/GitHub Pages with markdown) are preferred by engineering-heavy teams because they provide version history, PR review for changes, and keep documentation close to code. Notion is better for mixed engineering/non-engineering teams because it's easier to edit for non-technical contributors. Confluence suits organisations already on Atlassian tooling. The most important factor is adoption — choose the tool your team will actually use and maintain.