The Beginner in the Room
What documentation reveals about who belongs in software
What do you call the person in the room who does not understand the system yet?
There are a few possible answers. You might call them new. You might call them junior. You might call them a user, a student, a customer, a contributor, a teammate, or, if you are feeling particularly impatient, a blocker.
The name matters because the name tells us what we think is happening. If the person is a blocker, then their confusion is an obstacle to our velocity. If the person is junior, then their confusion is a temporary defect that seniority will eventually cure. If the person is a user, then their confusion is perhaps a ticket for someone else to triage. If the person is a student, then their confusion may be the beginning of something.
Software culture has a strange relationship with beginners. We celebrate learning in public, build whole brands around tutorials, and tell people there has never been a better time to get started. Then we design systems whose real instructions are hidden in tribal memory, stale wiki pages, half-complete examples, private chats, and that one engineer who knows why the deploy script has to be run twice on Thursdays.
We say we want more people in technology. We often build as if only the already initiated belong here.
The Moral Shape of Explanation
Documentation is usually treated as a productivity concern. Better docs mean fewer interruptions. Better onboarding means faster ramp time. Better tutorials mean lower support load. All of that is true, and none of it is the whole truth.
Explanation is also a moral act.
To explain something well is to make a claim about the person receiving the explanation. It says: you are capable of understanding this. You are worth the time it takes to make the path visible. The knowledge does not exist only for the people who already have the password to the room.
To explain something badly says something too. Sometimes it says we were rushed. Sometimes it says we were careless. Sometimes, if we are honest, it says we quietly enjoy the status that comes from being one of the few people who understands.
There is a particular kind of power in being the keeper of undocumented knowledge. Nobody announces it as power. It rarely appears on an org chart. Yet it shapes who gets invited into decisions, who becomes indispensable, who gets trusted, and who spends their first months at a job wondering whether they are failing or whether the system has simply been arranged against them.
John Dewey, in Democracy and Education, argued that education is not preparation for life. Education is life itself. He was writing about schools, but the insight travels cleanly into engineering. Learning is not the waiting room before real work begins. Learning is one of the main ways a community reproduces itself. What we teach, how we teach, and whom we imagine as teachable all reveal what kind of community we are.
A team that cannot teach itself to newcomers is not merely inefficient. It is brittle.
The Cult of Figuring It Out
There is a phrase that gets passed around in engineering with near-religious confidence: good engineers figure things out.
I believe this. I also distrust what we sometimes do with it.
There is a real and necessary discipline in learning how to investigate, search, test, read errors, trace behavior, and keep going when the first answer does not appear. Nobody becomes a serious technologist by being spoon-fed every step. The ability to sit with confusion without immediately collapsing into helplessness is part of the craft.
But there is a difference between productive struggle and ritual abandonment.
Productive struggle gives someone enough structure to build strength. Ritual abandonment tosses them into the deep end and calls drowning a character-building exercise. Productive struggle says, try this path first, and here is why it matters. Ritual abandonment says, we all suffered through this, so now it is your turn.
Maria Montessori wrote in The Absorbent Mind that the task of the teacher is not to pour knowledge into a passive mind, but to prepare an environment where the learner can act with growing independence. That distinction matters. Good instruction does not remove agency from the learner. It creates the conditions in which agency can become real.
There is a kind of documentation that does the opposite. It gives commands without context, examples without consequences, architectural diagrams without the story of why the architecture exists. It tells you where to click, but not what you are touching. It gets you through the happy path and leaves you stranded the first time reality wanders off script.
That is not empowerment. It is dependency with nicer formatting.
Beginners Are System Tests
The beginner sees what the expert has stopped seeing.
This is why beginner questions can be so irritating. They expose the places where our language has become shorthand for whole histories of decision-making. They reveal assumptions we forgot were assumptions. They ask why two things have the same name, why one service has three owners, why the official setup guide requires a version of a tool nobody has used in a year, why the error message says one thing when the fix is obviously another thing to everyone who already knows the fix.
The irritation is useful if we let it be useful.
The Talmud, in Ta'anit 7a, preserves a teaching from Rabbi Hanina: I learned much from my teachers, more from my colleagues, and most from my students. It is a beautiful line because it reverses the expected hierarchy. The student is not only a recipient of knowledge. The student is also a revealer of what the teacher has not yet understood.
Every beginner is a test of the system's honesty.
If a new teammate cannot complete local setup without three undocumented interventions, that is not merely a new teammate problem. If a customer cannot understand the pricing model without a sales call, that is not merely a customer problem. If an open project says contributions are welcome but keeps all real context in private channels, that is not merely a contributor problem.
Confusion is information. A mature culture listens to it.
Hospitality as Engineering Practice
Hospitality is not a word we use much in software, which is a shame. We talk about developer experience, onboarding, usability, enablement, and knowledge management. Those are useful terms. They are also easy to flatten into process.
Hospitality asks a more human question: what does it feel like to arrive here?
When someone opens the repository for the first time, what do they encounter? A clear path or a wall of assumptions? When someone joins the team, do they receive a map or a scavenger hunt? When someone asks a basic question, do they receive an answer that gives them dignity, or a link that tells them to disappear and come back after they have learned how to ask better?
This does not mean every expert must become endlessly available. Boundaries matter. Deep work matters. People should read what has already been written before demanding another human's attention. Hospitality is not servility.
It means we take responsibility for the threshold.
A threshold is the space between outside and inside. Every community has one. Every codebase has one. Every profession has one. Some thresholds are marked clearly: start here, then try this, then when it breaks, here is how to think about the breakage. Others are guarded by embarrassment, jargon, and the quiet suspicion that if you really belonged, you would already know.
Technology loves scale, but belonging does not scale automatically. It has to be designed into the small moments where people decide whether to keep going.
The beginner in the room is not an inconvenience to be managed until they become useful. The beginner is a reminder that our work is never only the artifact we ship. Our work is also the culture that teaches the next person how to touch it without fear.
Maybe the real test of a system is not whether an expert can make it sing. Experts can make almost anything sing. The better test is whether a capable stranger can approach it, ask an honest question, and leave with more courage than they arrived with.
What would we build differently if that were the standard?