The Engineering Culture Document That Engineers Actually Read

What you actually need to know

• Culture documents that list values without describing behaviors are not culture documents. They are PR documents.
• The test for a good culture document: would an engineer who joined the team recognize the description as accurate within the first month?
• Sharing the document with candidates during hiring produces better fits and fewer early departures.
• The document should describe the culture as it is, not as leadership wishes it to be. Aspirational documents destroy trust when reality does not match.
• Update the document when practices change. A document that does not track reality is worse than no document.

The core argument

The engineering culture document that engineers do not read is the one that says things like "we value collaboration, innovation, and continuous improvement." Every company's culture document says these things. They are indistinguishable from each other and from the culture document of a company with the opposite culture, because the values are stated at a level of abstraction where they can mean anything.

The document engineers actually read describes specific things. How does code review work? Can anyone block a merge, or only senior engineers? Is it expected that reviewers will catch correctness issues, or is the author responsible for correctness and reviewers responsible for style? These are questions engineers have when they join a team. A culture document that answers them is useful. A culture document that says "we believe in quality code and continuous improvement" is not.

The purpose of the culture document is dual. For new engineers joining the team, it is a reference for how to work well in the specific context of this team. For candidates evaluating the company, it is evidence about what working here is actually like. Both purposes require specificity. The new engineer needs to know actual practices, not principles. The candidate needs to be able to evaluate whether the described culture is one they will thrive in.

Writing the document is also a diagnostic exercise. When you try to write specifically about how code review works and find that there is no consistent answer, that reveals that the practice is not standard and needs to be. When you try to write about how technical decisions are made and find that different engineers have different mental models of the process, that reveals a gap that is causing friction. The act of writing the document surfaces these gaps, which is valuable independent of the document itself.

What the document should actually cover

Decision-making. Who makes which decisions? What decisions require consensus versus single-owner judgment? What is the process for architectural decisions that affect multiple teams? A concrete description of this resolves a significant source of confusion for engineers who are new to the team.

Code practices. What does code review mean for this team? How many approvals are required to merge? Is the author or the reviewer responsible for test coverage? What style and formatting standards apply, and how are they enforced? Is it acceptable to ship code that is functional but not well-structured if the timeline is tight, or is quality non-negotiable? These questions have different answers at different companies and the culture document should give the answers for this one.

Communication. Is the team primarily synchronous or asynchronous? What belongs in Slack versus what belongs in a ticket? What is the expected response time for messages from teammates? What is the escalation path when two engineers disagree? These norms determine a significant part of the day-to-day experience of working on the team.

Production. How does code get deployed? Who can trigger a production deployment without review? What is the incident response process when something breaks? Who is on call, how does on-call rotate, and what is the expectation when on call? Engineers who have been paged at 3 AM because of unclear on-call expectations will appreciate a team that has written this down.

Growth. How does promotion work? How is feedback given and when? Is there a formal performance review process? These are questions that affect the long-term arc of working on the team, and candidates who are evaluating multiple offers will factor them into their decision.

Making the document trustworthy

The culture document is only as trustworthy as the gap between what it describes and what is actually practiced. A document that says "we give thorough code reviews within 24 hours" that engineers ignore for days is not a trustworthy document -- it is a source of frustration for engineers whose experience does not match the written description.

The way to make the document trustworthy: write it from observation of current practice, not from aspirations, and get the team to validate it. Share the draft with the engineering team before publishing. Ask: "Is this accurate? Are there practices you experience differently?" The disagreements that emerge from this review are the most useful input -- they reveal the gaps between the documented culture and the real one.

When you change a practice, update the document. The document that describes practices from two years ago is actively misleading. It tells new engineers to expect something they will not find, which is worse than no document at all.

Common mistakes engineering leaders make with culture documents

1. Writing the document without team input. The leader's description of the culture is often idealized relative to the team's experience of it. Team input corrects this.
2. Using the document to announce aspirations rather than describe current practice. "We aspire to give thorough code reviews" tells the new engineer nothing about what to expect.
3. Not sharing the document with candidates. The culture document is one of the best filtering tools in hiring. Candidates who self-select out after reading it would have left early anyway.
4. Not updating the document when practices change. A stale document is worse than no document because it actively misleads.
5. Making the document too long. A 30-page culture document has the same problem as a 30-page legal agreement -- it is not read. Keep it specific and short enough to be read in one sitting.

Where to start: a 3-step culture document

Step 1: Interview three engineers on the team and ask them to describe the team's actual practices in the five areas above. Record their answers. Note where the answers differ from each other. The discrepancies are where the culture is unclear or inconsistent.

Step 2: Draft the document based on the observed practices, not the aspirations. For each section, write the most specific description you can. If the practice is not consistent enough to be described specifically, describe the inconsistency and note that a decision is needed.

Step 3: Share the draft with the full engineering team and ask for corrections. Frame it as a documentation exercise, not an evaluation. Ask: "Does this match what you experience?" Accept all corrections and publish the updated version.

The Culture That Is Already There

Yashveer Singh. Founder of Yashveer Labs. Writing the culture down for Yashveer Labs forced specificity about practices that had been implicit. The implicit practices that get written down become real commitments. That process is valuable independent of the document. If you are building an engineering team and want to think through how to document and sustain the culture, the contact page is there.

Related reading

• The Engineering Career Ladder That Engineers Trust
• The Engineering All Hands That Engineers Look Forward To
• The Annual Engineering Review That Engineers Actually Find Useful
• The Engineering Brand: Why It Matters More Than You Think