How to Create an Engineering Handbook 📖
A comprehensive guide that draws from our latest Mastermind session
I am, admittedly, a note-taking nerd.
I have written about this many times [1, 2, 3] 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.
This is what I was thinking when I joined our latest mastermind a few weeks ago, about Engineering Handbooks.
In our private community, we run a mastermind session every month: we vote on a topic, we join a 75 mins session facilitated by Joel (a professional CTO coach), and discuss our respective experiences.
After the session, Joel publishes the learnings on our forum, the conversation continues async, and I eventually turn the insights into the article you are reading right now.
So, this piece is the result of the collective knowledge of ~20 CTOs, engineering managers, and software engineers, who debated on engineering handbooks for weeks. And I have the steep task of turning it into a full article!
So, 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 Maintaining Handbooks — strategies to keep them relevant and up-to-date.
🌐 The Handbook-first approach — and how it transforms team communication and culture.
📌 The Final Cheatsheet — putting all together in a simple checklist
Let’s dive in!
📘 What is an Engineering Handbook?
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 minimize effort and maximize value. 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. More about them here.
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: