Writing a 'first week in a new codebase' post

Starting on a new codebase is one of the few times you still see it as a stranger would. Two weeks in, the weird folder name will feel normal; six months in, you will not remember what it was like to not know. That short stretch is useful on its own, and it is also the easiest material you will have for a blog post, if you write it down while it is still strange.

These notes are about turning the first five to ten days on an unfamiliar codebase into a post the next newcomer can use. It overlaps a little with our notes on writing a today I learned post, but the first-week post is a longer thing: fewer snappy lessons, more mapping out a territory.

Keep two running files

On day one, open two text files and keep them open all week.

The first is a plain log. Timestamps, what you did, what you tried, what broke, what someone told you in chat. It can be ugly:

Mon 09:30  Cloned repo, read README. Setup script asks for env vars I don't have.
Mon 10:15  Asked in #new-starters, got a link to a wiki page the README doesn't mention.
Mon 11:00  Tests pass locally but one is skipped. Why?
Tue 14:00  Found the skip: an old integration that still runs in staging.

The second file is a questions file. When you catch yourself confused, write a one-line entry in this file instead of tabbing away to figure it out. Each question gets a short answer later, or a note saying you asked and it turned out to be historical.

The log is where your blog post will come from. The questions file is for the post and for your own team: at the end of the week, the questions that still have no clean answer are a small gift to whoever looks after onboarding docs.

Write what you can share, not what you can't

A first-week post has a different trust problem from a short lesson. You are new, and the material comes from a codebase you do not own. Before you publish, read the draft once for anything that would surprise your employer:

• Names of internal services, repositories, or customers.
• Numbers that would read as a leak: user counts, revenue, uptime, cost figures.
• Screenshots of dashboards, admin tools or source files, even blurred.
• A colleague's sentence quoted without them knowing.
• Security details: where credentials live, what a bastion is called, how a deploy is signed.

Rename or generalise. "A service that handles billing" is fine; the service's real name is not. "Our auth code uses a hand-rolled session middleware" is fine if that is also true of a dozen other shops; naming the library you built on top is not. If you are uncertain whether something is sensitive, assume it is, and either strip it or ask. A short, honest post you can show your team beats a longer one you quietly hope they never see.

If your employer has a review-before-publish rule, use it. Sending a draft to a teammate or a manager and asking "is anything here off-limits?" is a two-minute ask that saves a lot of backtracking.

Confusion is the post

The temptation, once you understand something, is to write it up as if you always did. Resist it. The valuable thing about a first-week post is the shape of the confusion, not the eventual answer.

Imagine this notebook entry on day two:

The service uses two different HTTP client wrappers. One goes through a
retrying proxy, the other doesn't. I can't tell from the name which is
which, and the imports look the same in half the files.

A week later, you will know which wrapper is which. The post is not "here is the difference between the two wrappers" — your co-workers already knew that. The post is "on day two, I could not tell these two wrappers apart from their names, and here is what helped me finally see the difference." That is the piece a reader in the same boat will recognise.

The honest rule of thumb: write up moments where you were stuck for more than fifteen minutes, and the thing that broke you out. Not clever solutions you found on your own — a map through the confusion.

Keep the specifics generic

You will want concrete examples. Give them. Just do the small lift of translating them into shapes any reader could recognise.

# Too specific (gives away the shop)
We use AcmeAuth v4 and the session cookie is `acme_sid=...`.

# Portable (same point, no names)
We use a hand-rolled session middleware. The cookie name doesn't
match any library convention, which is what tripped me up when I
grepped for the login flow.

The portable version also travels better. A reader at another company can map "hand-rolled session middleware" onto theirs; they cannot do anything with your actual library name except guess at where you work.

End on questions, not answers

A first-week post should not pretend to be a tour by someone who already knows the building. It should end on what you still do not know.

Three or four honest open questions make a fine closing section. They might be as small as "I still cannot tell which of these two caches is the one tests use, and the README does not say." They are the follow-up posts you will write in month two and month six, and they let the reader know you are telling them where you actually are. That is the voice our guidelines ask for: argue with your own confusion, not pretend it is not there.

There is a quieter benefit. A list of open questions at the end of the post is a list of things you can ask about on day eleven, now that you have paid enough attention to ask them well. That is often the real payoff of writing one.

A rough template

If you want a shape to start from, this is one that holds up:

1. Where I came in. One short paragraph. What the system does, in one sentence; what you were asked to do first; what you already knew going in.
2. The first map. How you oriented yourself: which files you opened, which commands you ran, what your first mental picture turned out to be wrong about.
3. Three things that confused me. Pick the sharpest entries from your questions file. Describe the confusion first, then what resolved it.
4. What I'd tell a new me. The small practical bits you wish you had known on Monday.
5. Still open. The questions you do not yet have good answers to.

A short post following that shape, published after week one or two while the notes are warm, is usually enough. You can always write the deeper piece in month three when you understand the why behind the code. By then you will need a different kind of post anyway, closer to a project post-mortem than a first-week map.

Keep the log, keep the questions file, write the post before the strangeness fades. If a draft goes well and you would like to publish it here, ask for a writer invite on the contact page.