How to Document Your Engineering Culture for New Hires

If you sit behind a new engineer during their first week, you will watch them stare at a pull request template for twenty minutes. They are not reading the code. They are trying to figure out if it is acceptable to merge a fix for a typo without pinging the tech lead, or if that will result in a passive-aggressive Slack message at 4:00 PM.

They are trying to read the culture.

We like to pretend that engineering culture lives in a slide deck presented by HR on day one. We put words like "Ownership" and "Blamelessness" in bold font and assume the job is done.

It is not done.

Culture is not what leadership wishes were true. Culture is what happens when things go wrong, how technical disagreements resolve, and what unwritten rules burn people when violated. When a company is small, this knowledge transfers through osmosis. You learn the calendar etiquette because you sit next to the person who manages the calendar. You learn what "quality" means because the CTO reviews your first ten commits.

Then you grow. Or you go remote. Or your senior engineers get tired of answering the same questions in the #onboarding channel. Suddenly, new hires are taking three months to become productive, and they are making mistakes that everyone else considers obvious.

You cannot fix this with a better values document. You fix this by documenting the operational reality of how your team ships software.

The Trap of the Values Document

There is a distinct difference between aspirational culture decks and operational documentation. The former describes what leadership wishes were true. The latter tells new hires how to survive their first 90 days.

When HR owns the documentation of engineering culture, the result is almost always aspirational. HR can own the company values, but engineering leadership must own the operational reality. If this becomes an HR project, it will drift into abstraction and miss the details that actually matter to an engineer trying to push code. The right owner for this documentation is someone who knows exactly what happens when things go wrong, not just what happens on the happy path.

Documenting culture is not a branding exercise. It is an exercise in operational risk mitigation. When an organization cannot afford to lose productivity to cultural confusion during onboarding, they need a structured approach to codify what has previously been informal or tribal.

There is a second failure mode that is less obvious: the document that is technically accurate but incomplete in the ways that matter. It describes the formal decision-making process but not the informal one. It says "we value async communication" but does not explain that the CTO still expects a response to Slack messages within the hour. It covers the org chart but not the actual power structure. New hires read it, feel like they understand the culture, and then spend six months learning the real rules through a series of uncomfortable surprises.

The most useful culture documentation is not comprehensive. It is honest. It describes the actual behavior of the team, not the aspirational behavior. That means it has to be written by someone close enough to the work to know the difference.

There is a version of this that companies get right. It is usually written by a senior engineer who has been around long enough to have seen new hires fail in predictable ways, and who is frustrated enough to do something about it. It reads less like a policy document and more like a letter to a new colleague: here is what I wish someone had told me, here is what will get you in trouble, here is how we actually make decisions. That document is worth more than any values deck.

What to Document (And What to Skip)

Most companies stop at values statements. The reader needs to know what concrete practices, norms, and workflows carry culture. The list is longer than most people expect.

How decisions actually get made is not the same as the org chart story. In most engineering organizations, the org chart describes the formal authority structure. The actual decision-making process is a different thing entirely. Who has veto power over architectural choices? What happens when the tech lead and the product manager disagree? What does "consensus" mean in practice? These are the questions a new hire needs answered, and they are almost never in the documentation.

What "quality" means in practice is another one. How rigorous is code review? What gets flagged versus what slides? Is a comment in a PR a suggestion or a requirement? If a reviewer leaves a comment and the author disagrees, what happens? These are not abstract questions. They determine how a new engineer behaves in their first month, and getting them wrong has consequences.

Communication norms are similarly specific. Async versus sync, when to Slack versus email versus call a meeting, escalation paths. Many teams say they are async-first but have a culture where not responding to a Slack message within two hours is considered rude. The written norm and the actual norm are different. Document the actual norm.

Ownership expectations are worth spelling out explicitly. How much autonomy does a new engineer have? When should they ask for help? What does failure look like, and how is it handled? The answer to "what does failure look like" is one of the most culturally loaded questions in any organization, and it is almost never written down.

How technical disagreements resolve is a question that new engineers are often afraid to ask. Whose judgment wins? Is there an appeals process? What happens when someone is overruled and they still think they are right? The answer to this question tells you more about the engineering culture than any values statement.

And then there are the unwritten rules that burn people when violated. Meeting lateness. Calendar etiquette. Friday deploys. These are the rules that senior engineers know and junior engineers learn the hard way. They are not in any document because no one thought to write them down.

The Friday deploy rule is a good example. Some teams have an explicit policy against deploying on Fridays. Others have an informal norm that everyone understands. Others have no norm at all, and whether a Friday deploy is acceptable depends entirely on who is on call that weekend. A new hire who deploys on a Friday and causes an incident will learn the norm quickly, but the lesson will be expensive. Writing it down costs nothing.

Where Culture Actually Lives in the Codebase

Engineering culture is embedded in the artifacts of your workflow. It is not just social norms; it is codified in how the team builds, tests, and ships code.

It lives in commit message conventions and PR description standards. It lives in how the team uses feature flags, testing standards, and CI/CD norms. It lives in incident response protocols and the tone of your blameless postmortems. It lives in how architectural decisions are documented, or not documented. It lives in wikis, README files, Slack channels, and someone's head.

If you want to document your culture, you have to document these practices. A new hire does not need to know that the company values "move fast and break things." They need to know if they are allowed to deploy on a Friday afternoon. They need to know whose judgment wins when two senior engineers disagree on an architecture choice, and what the appeals process looks like.

Consider the blameless postmortem. Many teams claim to have a blameless culture. But if you read their incident reports, you will find sentences like "Developer X deployed the bad config." That is not blameless. A truly blameless culture, as described by Google's SRE workbook, focuses on the systemic failures that allowed the bad config to be deployed. The culture is codified in the template of the postmortem itself.

Architectural Decision Records (ADRs) are another artifact where culture is embedded. If the team uses ADRs, the pattern of which decisions get an ADR and which do not tells you something about what the team considers architecturally significant. If the team does not use ADRs, that tells you something too. Either way, a new hire who does not know the convention will make decisions without the context that shaped them.

How to Capture What Is Currently Tribal

Most of this knowledge is locked in the heads of your senior engineers. It is tribal knowledge, and tribal knowledge is just working memory — it does not scale.

To extract it, you have to observe the friction points.

Shadow a new hire's first two weeks and write down every moment of confusion. Interview engineers at the six-month mark about what surprised them most when they joined. Interview engineers at the two-year mark about what they wish they had known earlier. Audit recent incidents and near-misses for moments where someone "should have known" something that was never written down.

The answers senior engineers give in Slack channels are often the best documentation you have. When a junior developer asks, "Do I need to update the ADR for this minor change?", the response they get is the actual culture. Capture that response. Turn it into a document. The next time someone asks the same question, they will find the answer without interrupting anyone.

This process will also reveal the gaps between the written culture and the actual culture. If the onboarding documentation says "we always write unit tests" but the senior engineer's answer in Slack is "it depends on the deadline," that gap is worth documenting. Not to shame anyone, but because the new hire needs to know the real answer.

The DORA research program, which has studied software delivery performance across thousands of organizations, consistently finds that generative organizational cultures — those with high information flow, shared risk, and failure treated as inquiry rather than blame — are predictive of better software delivery outcomes. The mechanism is not mysterious. When people know the real rules, they can operate within them. When they have to guess, they make mistakes.

The goal here is not to replace mentorship or human connection. The point is to reduce the time senior engineers spend explaining the basics so they can spend that time on higher-value coaching.

When the Documentation Breaks Down

No culture document survives contact with reality unchanged.

The most common failure mode is staleness. The team moves on to a new way of handling feature flags, but the onboarding wiki still describes the old way. New hires learn to ignore the wiki, and you are back to tribal knowledge. This happens faster than most people expect. A team that ships frequently can outpace its documentation in a matter of months.

Another failure mode is length. If the document is too long, no one will read it. It needs to be scannable, not comprehensive. It is a survival guide for the first 90 days, not an encyclopedia. The instinct to be thorough is understandable, but a 200-page onboarding document is functionally equivalent to no onboarding document. New hires will skim it, miss the important parts, and ask the same questions anyway.

It also fails when it describes an old culture and the team has moved on. Organizations change. The engineering culture at a 20-person startup is different from the culture at a 200-person company, even if it is the same company. If the documentation was written during the startup phase and the company has since scaled, the document is describing a team that no longer exists.

And it fails when it gets treated as law instead of a living guide. If the document says "we always write unit tests," but the reality is that the team frequently skips them to meet deadlines, the document is a lie. The new hire will quickly realize that the written culture and the actual culture are disconnected. Once that happens, they will stop trusting the documentation entirely, and you have lost the investment.

The Maintenance Problem

Culture documentation requires the same discipline as code documentation. If it is not tied to a review cycle, it will rot.

You need a specific human (not "the team," but a named individual) responsible for updating the onboarding materials. These updates should happen quarterly, or after significant organizational changes, or when onboarding feedback reveals gaps. The person responsible should be someone close enough to the engineering work to notice when the documentation has drifted from reality.

More importantly, the maintenance process needs to be integrated into the engineering workflow itself. When the team changes how they write release notes, or updates their API reference standards, or shifts their incident response protocol, the culture documentation should be updated at the same time. If the update to the documentation is a separate task that gets added to a backlog, it will never happen.

This is where the operational burden usually becomes too heavy for lean teams. Keeping documentation current requires constant vigilance. Every time the team changes how they write release notes, or updates their API reference standards, the culture shifts slightly. The documentation needs to shift with it.

The practical constraint here is headcount. Most engineering teams do not have a dedicated documentation engineer. The senior engineers who know the culture best are the ones who can least afford to spend their time maintaining a wiki.

If you want to keep culture documentation current without dedicating headcount to it, you need a system that pulls operational knowledge directly from version control and release cycles. Doc Holiday is built for exactly this. It drafts release notes, changelogs, and API references from your engineering workflows — but those drafts go through human review before anything is published. A senior engineer validates the output in a dashboard, catches what the automated pass missed, and approves the final version. That review step is not optional; it is the mechanism that keeps the documentation accurate. By making generation the first step and human validation the required second step, it gives your senior engineers the leverage to manage operational knowledge without spending their days rewriting the wiki from scratch.