Notes When Starting a New Codebase: A First-Month Log

2026-10-12 · Yesterself

You will never understand this codebase as badly as you do today. That sounds like the problem. It is also the only asset you have that nobody else on the team still owns, and it has a short shelf life.

Within about six weeks, most of what confuses you now will have quietly resolved into the way things are. You will not remember deciding it was fine. The strangeness will simply stop registering, the same way you stop hearing a fridge. You pay for competence in sight, and the only part you control is whether you wrote anything down first.

The window closes on its own schedule

In 1985 Peter Naur argued in "Programming as Theory Building" that a program's real content is a theory held in the heads of the people who built it. The source and the docs are traces of that theory, not the thing itself. A new person's real job is not reading the code but rebuilding the theory from the traces.

That tells you what the log is for. Every place your reconstruction fails is a place where the traces were insufficient. Nobody who already holds the theory can find those places, because from inside the theory the traces look complete.

There is a neat demonstration of that failure mode. Elizabeth Newton's Stanford experiments around 1990 had one person tap out a well known song on a table while another tried to name it. Tappers, hearing the melody in their heads, expected listeners to get about half of them. Listeners identified almost none. Once you know the tune, you cannot hear the taps.

Six weeks in, you become the tapper. Make the record while you are still the listener: in flight, badly, without stopping to research first.

Four marks, twenty seconds each

Keep capture cheap enough to do while you are annoyed. Four kinds of entry, one line each, dated:

• WHY — anything surprising. "Why do two services both own the user table?" Write the question and move on; chasing it now is how an afternoon disappears.
• STUCK — anything that cost more than fifteen minutes, with how long it took and what finally unstuck you. The minutes are the part that makes this legible to a manager later.
• WORD — a term used as though it were obvious. "The shim." "Prod-lite." "A soft delete, but not that kind." Internal nouns are the cheapest thing to hand over and the last thing anybody writes down.
• GUESS — your current theory, committed before you learn the answer. "I think the second auth path exists because of an acquisition."

The guesses are the entries that pay. Writing one before you ask makes the real answer stick harder than being told would. And a wrong guess is wrong in a way that matters: the next person to arrive will guess the same thing, so it belongs in the onboarding document verbatim, as the misconception to head off.

A rhythm for the first four weeks

Five minutes at the end of the day, ten on Friday. That is the whole commitment, and the weeks have different centers of gravity.

1. Week one: geography and vocabulary. Where things live, what things are called, and the setup path written step by literal step, including everything somebody had to tell you in person.
2. Week two: friction. Your first real ticket. This is when STUCK entries arrive in volume, because this is the week the map meets the ground.
3. Week three: guesses. You now know enough to have theories. Write them before you ask anyone.
4. Week four: answers. Work back through the open WHY entries, answering what you can and noting who told you. That side effect is its own map of who holds which part of the theory.

Miss days without ceremony. A three-day gap describes the week you had, not a broken chain, and Friday still catches the two things that cost you most.

Where the log lives

Not in the repository, and not in the team wiki while it is raw. The raw log contains irritation, names, and provisional judgments about people you have known for eleven days. That is fine in a private register and corrosive in a shared one. This is the same split that separates a team's architecture decision record from your own private decision log, and the same reason a debugging log is more honest when it is not performed for an audience.

One plain caveat, because this is a record about work: none of this is legal advice. What counts as confidential material is set by your contract and by where you work, not by where you store a file. If an entry touches customer data, an incident, or another person's conduct, ask before it leaves the company's machine.

Then schedule the reading. A log reviewed when you happen to remember it is reviewed never, and the booking has to be made by the version of you who still remembers being lost. Yesterself, a journaling app, is built on that principle: a sentence can be postmarked to a future date and arrives that morning as mail, so on your first afternoon you can send "which of these can I no longer understand being confused by?" to day thirty. The mechanism matters more than the tool.

Converting the log into onboarding docs

Around day thirty, the log becomes raw material. Six rules make the conversion quick.

1. Ship only what had a cost. Sort the STUCK entries by minutes lost. The top ten are your document; the rest is noise you happen to have written.
2. If it can be fixed instead, fix it. A paragraph explaining a workaround for a broken setup script is worse than a one-line patch. Documentation is what you write when the fix is out of your hands.
3. Put the answer next to the question, in the words week-one you would have understood. Not the correct words. The understandable ones.
4. Make the setup path replayable. A list somebody can follow top to bottom without asking a human. Every step you were told verbally is a step that was missing.
5. Turn WORD entries into a glossary. One line each: what the thing is and where it lives.
6. Keep your feelings out of it. "This is a mess" helps nobody and outlives your good mood. The entry underneath it, the concrete confusion, is the part that transfers.

Hand it to the next person who joins and ask them to log against it. A document that is never corrected by its next reader is decoration.

Turning the rest into 1:1 questions

Do not fire every WHY the moment it appears. Batch them and sort into three piles, because they want different rooms.

Blocked goes to chat immediately. Waiting for a scheduled meeting to unblock yourself is expensive, and reads as timidity rather than politeness.

History goes to the 1:1. "There are two auth paths. What was going on when the second one was added?" Asking what was true at the time assumes there was a constraint you cannot see, which is almost always correct. They are free knowledge and cost nobody much to answer.

Judgment about how the place works goes last, and goes with a number attached. Nobody can act on "onboarding was rough." Anybody can act on "setup took me eleven hours and nine of them were one missing environment variable. Worth me writing that down?" Your log is the only reason you have the number, and the number is why the observation lands as help rather than complaint.

Ask all of it in the first month, the only period when having questions is expected rather than alarming. A question saved for later is not more polite, just later and stranger.

Read it at thirty days, and again at ninety

Two things show up. The entries whose confusion you can no longer reconstruct are exactly the ones to ship: they mark where the theory finished forming and the sight went. And entries still unanswered at ninety days are not your ignorance anymore. Either nobody knows, or the answer is history nobody wrote down, and both are worth naming out loud.

By then you will be fluent, useful, and no longer able to see the thing you saw in week one. The log is the only copy.

Common questions

How long should I keep a learning log for a new codebase?

Through the first month, and then read it again at day ninety. The entries stop appearing on their own, which is the signal that the window has closed rather than a sign you have run out of discipline.

Will asking why is it like this make me look critical?

Not if you ask about history instead of judgment. Something like what was true when this was decided invites the story, assumes there was a constraint you cannot see, and is usually answered generously.

Should the log live in the company wiki?

Not while it is raw. The raw log contains frustration, names, and half-formed guesses about people you have known for a week. Keep it private and ship a cleaned subset as the onboarding document.

What if I miss three days in a row?

Nothing breaks. A gap is information about the week you had, not a failure, and Friday is enough to catch the two things that cost you the most time.

Do I need to write the answers down too?

Yes, next to the original question, in words the version of you from week one would have understood. A question with no answer beside it is not usable by the next person who arrives.