I have written about this many times, and I guess I will keep doing that, because 1) good writing, in both work and life, seems to be constantly underrated, and 2) my workflows change over time, and I can’t help but write about them.
Also, my work as a full-time writer is a note-taker's dream. My output is very directly connected to the quality of my note-taking: the better I am at managing my knowledge, the faster and better I am able to turn it into articles.
Even in my past lives, as CTO first and Head of Engineering later, I have always been the docs guy. I introduced Notion at my startup in 2018, and tweaked it endlessly to create the perfect workspace for us.
All this passion didn’t save me from making mistakes. Actually, a lot of them.
Many (most?) of our docs grew stale and irrelevant. Our structures so complex that people couldn’t find even basic information. We declared doc bankruptcy and started over more than once.
Over time I spoke with many CTOs and engineering leaders about similar struggles: readers, community members, or just friends, and debated this ad nauseam. We have also run ad-hoc community masterminds and threads about this very topic 👇
So, today’s piece is the result of the collective knowledge of several tens of people, on how to create a functional, sustainable engineering handbook for your team.
Here is what we will explore today:
📘 What is an Engineering Handbook — and why it is a crucial investment for your team.
🏗️ Structuring your Handbook — to ensure it is comprehensive yet easy to navigate.
📝 Creating and MaintainingHandbooks — strategies to keep them relevant and up-to-date.
🌐 The Handbook-first approach — and how it transforms team communication and culture.
📌 TheFinal Cheatsheet — putting all together in a simple checklist
Let’s dive in!
📣 Brought to you by:
This monthly free article is brought to you by today’s sponsor, Augment Code!
Augment Code is the only AI coding agent built for real engineering teams.
It understands your codebase—across 10M+ lines, 10k+ files, and every repo in your stack—so it can actually help: writing functions, fixing CI issues, triaging incidents, and reviewing PRs.
All from your IDE or terminal. No vibes. Just progress.
An Engineering Handbook is the guide to how your engineering team works.
It serves both as a cultural repository, capturing your team’s collective wisdom, and as an operational guide, explaining how the team should function day-to-day.
Handbooks come in many forms, the most popular of which are digital docs (wikis, Notion, Confluence, …), and code repositories — i.e. markdown files that live together with code, like GitLab's public handbook.
In some companies handbooks get also printed as physical books, and given to new employees. This is less common but still pretty much in use, like at Valve.
Handbooks for engineering teams typically cover three key areas:
🛠️ Technical practices — coding standards, development processes, and tech stack details.
🤝 Team dynamics — communication, collaboration guidelines, and decision-making processes.
🌱 Growth and onboarding — how new members join and how existing members develop their skills.
In short, it's a living document that reflects and shapes how your team collaborates to build great software.
The living part is crucial. As Umberto Nicoletti, Head of R&D, put it in the community thread:
"Rules are made to serve us, not for us to serve the rules."
The handbook is a tool to empower your team, not constrain it. To achieve this, teams need to keep it relevant and up to date, which is tricky, but well worth it. A good handbook, in fact, enables:
🚀 Speed — it makes onboarding and decision-making faster by providing clear, accessible guidance.
🔄 Consistency — it ensures uniform practices across projects and team members.
🌐 Scalability — it enables teams to grow and work asynchronously by codifying knowledge and processes.
So, let’s see how to structure your handbook 👇
🏗️ Structuring your Handbook
Handbooks should be easy to understand and navigate, because engineers have to actually want to use it.
This is the #1 quality you should aim to achieve — before it being comprehensive, detailed, or whatever you might think of.
When something is easy to understand, it is easy to update. When it is easy to navigate, things are easy to find. Remove these qualities, and over time handbooks become forgotten dusty tomes sitting in a (digital) corner.
To reflect on how to build your handbook, let’s cover three things: organization principles, sections, and modularity.
1) 🗂️ Organization Principles
Documentation is a game where players are, in turn, either readers or writers.
As a reader, I want to easily find and read valuable information about what I need. As a writer, I want to easily write about what I am working on and contribute to the company knowledge.
In both cases, we want to minimizeeffort and maximizevalue. So, without getting into any particular structure or tool, these are the qualities we should optimize docs for:
🔄 Reusable — Design your notes to be easily reused and connected. The more information is reused, the more value it provides and the easier it repays the cost of writing it. For reusability, the best strategy is to have notes/pages that are small and cohesive. Create a note around a single concept, and link it to all the other notes where this concept is mentioned or useful.
🔍 Discoverable — Make content easy to find. Whatever tool you use, create a simple structure and avoid excessive nesting. Prefer tags (if you can) to deep subfolders, and make navigation as easy as possible. E.g. for their internal docs, Notion has ditched folders in favor of a global database organized with labels.
🍱 Contextual — Organize notes around how you will use them. Think about what they are useful for, in which situations you will need them, and put them there.
2) 📚 Core Sections
There is no one-size-fits-all structure for a handbook, but these are sections you might consider:
Company vision & mission — This sets the tone for everything else. We discussed it in this recent piece.
Domain knowledge — if your business operates in a space that requires specific domain knowledge (e.g. finance), you may have a section that teaches the basics.
Engineering principles — they answer the "why" behind your engineering practices. It’s the set of your shared engineering beliefs, that guide how decisions should be made.
Dev process — How do you build and ship software? This covers your SDLC, from planning to deployment.
Tech guidelines — Your coding standards, design principles, and best practices. Aren’t these the same thing as the engineering principles? Not exactly: principles are cultural stances, e.g. “fix problems even when they are not yours”, guidelines are tactical rules, e.g. linting and naming conventions.
Team collaboration — How do engineers work together? This includes meeting structures, stakeholders, pairing, and everything around ceremonies.
Onboarding — how new engineers get up to speed. There might be specific docs about your first week, how to setup your dev environment, etc.
Career growth — how team members can grow their careers. This includes career frameworks, reviews, promotion cycles, and HR stuff.
Again, you shouldn’t probably create all of this: for some companies, domain knowledge is irrelevant. For small teams, career growth is just a few lines. And so on. Consider this as a checklist that you can go through and take inspiration from.
For example, Mirco Franzek, Senior Backend Developer, shared in the community discussion how his team structures their handbook:
"Our handbook is roughly divided into four parts: onboarding, daily work, development information, and business logic. The 'daily work' section is read and updated most often."
This approach is totally fine: it balances the needs of new hires with the day-to-day requirements of the existing team.
All in all, it is more important for the handbook to be clear and useful than to be comprehensive. So, as Ross Younger said, start small:
"When it comes to getting the first version out, my advice would be to start small. Start with what matters most to your team and let it evolve. Be prepared to insert placeholders for sections you think you ought to write later, but also be prepared to change your mind."
Your handbook's structure should serve your team's needs. Don't be afraid to experiment and iterate. The best structure is the one that your team actually uses and finds valuable.
📝 Creating and maintaining handbooks
A well-structured handbook is great, but the real challenge lies in creating and maintaining it. Let's explore how to make this process smooth and sustainable:
1) 🚀 Kicking off
If you don’t have a lot in place, or what you have is old / unreliable / not much used, you should probably restart from scratch.
Starting fresh creates positive momentum and allows everyone to contribute without biases/attachments to what exists. If you are doing that, consider a three-step process:
Document what you have — start by writing down your current practices. Don't aim for perfection, just capture what you're actually doing.
Identify gaps — as you document, you'll naturally spot areas where guidance is missing or unclear. These are the practices where people disagree on how to perform them: might be code reviews, design docs, or else. Just make note of these and move on. Don’t aim to fix everything on the spot.
Prioritize and fill — schedule the work to fill the gaps, starting with the most critical ones. Get to a first version that is acceptable, and move on to the next phase 👇
2) 🌱 The Gardener
Maintaining docs is often compared to gardening: good gardeners do a few small things everyday, instead of big batches of isolated work. Once your handbook is in a good state, you should nail the basics of contribution:
Assign a gardener — I am a big believer in having a direct responsible individual for your handbook. While contributions should come from everyone (more on that below), it’s important to have someone who has the meta-job of keeping the whole work relevant. Is the structure good? Is the handbook being used? What can we do better? When contribution is 100% bottom up, without a single owner, the risk is nobody asks these questions.
Encourage contribution — the gardener should prod team members to contribute to the handbook, and make it easy for them to do so. Is the structure clear? Are there good templates in place? Aim to remove all kinds of thinking people should do before contributing.
Establish the boy scout rule — just like they should do with code, people should always leave the handbook in a better state than they found it. When anyone finds a small gap, it is best to fill it on the spot. This is infinitely easier than letting problems pile up, like with tech debt.
Prune outdated content — the limit of the boy scout rule is that it only works for stuff that actually gets updated. But a lot of content simply becomes irrelevant over time, and it’s important to prune it to keep the space decluttered. While this can be done by anyone, in my experience it is mostly up to the gardener.
Shout-out to Ezequiel Actis Grosso, fractional CTO, who introduced the gardener topic in our discussion:
"Another aspect I think is important is the role of the 'Gardener' — or what Notion refers to as a Librarian. It helps to keep the content curated, up-to-date, and valuable — more 'gardening' than 'policing,' similar to the mindset around code ownership."
3) 🔗 Integrate into existing workflows
Finally, for the handbook to stay relevant, maintaining it should feel natural, not like an extra chore. To do that, the best way I know is to integrate it into existing processes. In my experience, these are the easiest ones:
Onboarding — make new hires update relevant handbook sections as a part of the onboarding process. This is such a win-win-win: new hires can easily spot gaps precisely because they are new, they bring fresh perspectives, and for them it’s a good task that delivers real impact.
Retrospectives / Postmortems — after significant projects, incidents, or simply in periodic retrospectives, update the handbook with lessons learned. To make sure you do so, create an agenda for these meetings and include handbook update as a bullet point.
Tech decisions — Whenever you make important technical decisions, ask yourself if you should reflect these in your handbook. Structured formats like ADRs (Architecture Decision Records) can be linked or integrated directly.
So my TL;DR is: 1) start with a solid (if small) first version, 2) assign an owner, 3) distribute the responsibilities, and 4) link to processes.
🌐 Handbook-first
As we close this guide, I want to reflect on how teams actually use their handbooks, and what makes the difference between success and failure.
In my experience, there are three levels of handbook adoption that teams go through: handbook-free, handbook-supported, and handbook-first.
Let's explore each of them.
1) 🙅♂️ Handbook-free — people are the documentation
Most teams start here. Knowledge lives in people's heads and is transmitted through conversations. This works fine when teams are small and everyone talks to each other frequently.
However, when teams grow or become distributed, this approach breaks down. Knowledge gets lost, inconsistencies arise, and onboarding new people becomes super long.
This leads to the infamous hyperactive hive mind, as Clemens Adolphs points out:
"An engineering handbook is one of many important tools to employ combating what Cal Newport calls the 'hyperactive hive mind' way of working. You've all seen that way, where work unfolds in a series of asynchronous, unstructured, ad-hoc messages. A handbook approach is calmer but takes time and effort."
To leave this stage you need to start documenting things 👇
2) 🥈 Handbook-supported — the unstable middle
This is where many teams land in their first attempt at documentation. The typical pattern is:
Conversations mostly happen in meetings and chat
Decisions are taken and later (often begrudgingly/hastily) reported in docs
Documentation is seen as a chore, something you do after the real work
But here's the key insight: this is not a stable state. One of two things typically happens:
❌ If documentation always comes after decisions, there is little benefit in having docs at all. Over time, they become outdated and forgotten, effectively reverting to "no handbook".
✅ If teams start seeing the benefits of documentation, they naturally move towards a handbook-first approach. The virtuous cycle begins when docs start preventing sync conversations from happening, thus saving time.
In a handbook-first culture, the dynamic changes completely:
Fewer conversations happen, and they often start from documentation.
Decisions are made because of documentation, not the other way around.
The handbook becomes a tool for thinking, not just recording.
Teams that successfully adopt a handbook-first approach are more resilient and do clearer thinking. In fact, writing things down just makes your thinking better (trust me on this, I am a writer) and often reveals gaps in logic or process that weren't apparent in conversation.
It also makes knowledge a team quality, rather than a personal one, so that it doesn't walk out the door when people leave. And new team members can quickly get up to speed by reading documented processes and decisions.
🏢 Real-world examples
Some companies have mastered the handbook-first approach:
GitLab — leads by example with their public handbook, which has become the gold standard for transparent documentation. They use it for everything from engineering practices to company values.
Resend — shows how smaller companies can adopt this approach effectively. They maintain a manageable but comprehensive handbook that grows with their team.
Linear — demonstrates how documentation can be seamlessly integrated into product development. Their "Linear Method" publicly documents not just processes, but the principles behind how they build software, influencing both their team's work and their product design.
So, a handbook isn't just a document — it's a fundamental shift in how your team thinks, communicates, and makes decisions. When done right, it becomes an integral part of your engineering culture, driving both efficiency and quality.
📌 Bottom Line
So, thank you for making it this far 🙏
Here is the final cheatsheet for engineering handbooks:
📘 Purpose — a handbook serves as both a cultural repository and an operational guide for your engineering team.
🏗️ Structure — focus on three core areas:
Technical practices and standards
Team dynamics and communication
Growth and onboarding processes
📈 Evolution — teams typically go through three stages:
No handbook (tribal knowledge)
Handbook-supported (docs after decisions)
Handbook-first (docs drive decisions)
🎯 Success factors — focus on these:
Assign a dedicated owner (the "gardener")
Keep it simple and easy to navigate
Integrate updates into existing workflows
Start small and grow gradually
❗ Common pitfalls — watch out for these:
Making it too comprehensive too soon
Letting it become outdated
Treating it as a standalone tool rather than part of your culture
Remember: the goal isn't perfection, but usefulness. A slightly messy but actively used handbook is far better than a pristine one that nobody reads.
