The README is “coming soon.” The wiki is a 2019 screenshot. Slack history is in a workspace you are not in. You are expected to ship a small ticket this week. This is normal. It is also learnable.
Onboarding onto an undocumented repo is a research project with a deadline. You do not need to understand everything. You need a loop: run it, change it, find the people, write down what you wish had existed.
This is a sequence that works when documentation is a ghost.
Day one: run it
Your first deliverable is the app running locally, even if the feature is a button that already works. README, .env.example, Compose, make, package.json scripts. When it fails, write down the failure. That list is the start of the README you will add.
If you cannot run it in a day, the environment is the first ticket, not your feature. Tell your manager. Sitting stuck in silence is how week two starts with nothing.
Get a second data point: CI. If CI is green and local is not, you are missing a step. Copy the CI setup. If CI is red, the repo is already on fire. That is useful information.
Find the spine
Every app has a spine: request in, response out. HTTP router, a worker, a page. Find the entry: main.ts, cmd/server, app/page.tsx. Trace one request through. Do not trace all requests.
Draw a crude diagram for yourself: browser → API → DB. Add Redis if you see it. This diagram is the map. Update it.
Search for the domain words from your ticket: invoice, coupon. git grep beats reading files in alphabetical order.
Tests and types as docs
If tests exist, read the ones named after your feature. They show intended behavior, including the ugly cases. If types exist, the function signatures are docs that compile.
If there are no tests, your first commit might be a characterization test, not the feature. That is not delay. That is a flashlight.
Git history is the wiki
git log -- path on the scary file. git blame for the weird if. The commit message, if anyone followed the Artikals git article, will explain the tax exception. If the message is “fix,” look at the PR number in the merge commit and hope GitHub still has the discussion.
PRs are better than files. Search the PR list for the feature name.
People are the real documentation
Ask who last touched the module. Ask for 20 minutes, with a specific question: “Where should a new refund reason live?” not “How does the backend work?” Specific questions get specific answers. Tours get folklore.
Write down the answer in the repo, in a comment or a short docs/refunds.md. If you only put it in Notion, the next person will miss it. If you only put it in a comment, it might rot. Prefer both for dangerous modules.
If people are gone, the issue tracker is the oral history. Search closed tickets.
Permissions, prod, and fear
Do not request prod access on day one unless you need it. Read-only logs might be enough. Breaking prod on day three is a famous genre.
If you must look at prod data, follow the policy. PII is not a learning toy.
The small ticket strategy
Pick a ticket that touches one layer if you can: copy, a clear bug, a log line. Ship it to learn the PR machine, CI, and review culture. A large feature as the first PR is how you mix learning the business with learning the release button.
If the only tickets are large, slice a logging or metric task with your lead. You still need a first merge.
Leave the campground better
Update .env.example. Add the missing Compose port note. Fix the README command that is wrong. This is not extra credit. This is how the company stops paying the onboarding tax.
Do not write a 40-page architecture doc from guesses. Write the five commands that work.
A one-week checklist
- App runs locally
- You know the entrypoint and the DB
- You grepped your domain words
- You asked one human one specific question
- You merged something small
- You wrote down one thing that was missing
If you did that, you onboarded. You are not supposed to know the whole monolith. Nobody does. They know a region. Start a region.
Feature flags and your ticket
If the feature is flagged off in local .env and on in prod, you will think you built it and QA will think you did not. Search FLAG_ and the product name. Ask which default you should use locally. Put it in .env.example.
The opposite: the flag is on for staff in prod and you are not staff, so you cannot even see the screen you are supposed to change. Get yourself in the allowlist. This is not a joke. It wastes days.
Seed data and the empty app
A local app with no users looks “broken.” Find seed, fixtures, or a Storybook. If there is none, creating one user through the UI is the first quest. Write the email you used in your notes. Do not use a real customer email.
If seeds assume a specific id (user id 1 is admin), tests and local will fight. Learn that assumption before you “fix” the id sequence.
Observability on day two
When you can, open the staging APM and find the route you will change. Seeing the real SQL is faster than reading every repository class. If you have no staging, ask for it. Developing only against prod is a rite of passage you should skip.
The build you should not skip
If the app needs a generated GraphQL client or a protobuf step, missing it looks like “the types are wrong.” Run the generate script. Put it in postinstall only if the team already does that; otherwise document it in the first ten lines of the README you are about to write.
If there are multiple packages in a monorepo, learn pnpm --filter or nx run for the one you need. Building the entire monorepo to change a button is a tax you can often avoid.
When to ask for a tour
After you can run the app and have grepped your domain, a 20-minute tour is high leverage. Before that, the tour is a blur. Prepare three questions. Take notes in the repo. Send a thank-you with the notes so they can correct mistakes. That email is documentation.
Editor setup is part of onboarding
If the repo has an .editorconfig, Prettier, or ESLint, install them before you fight style review. If there is a VS Code workspace recommendation, use it. Half of “the code looks wrong” is a missing extension. Put that in the README you write.
Access that is not in the README
VPN, SSO app assignment, GitHub org, npm token, Docker registry. Make a checklist of “things I had to request.” Put it in the onboarding doc. The next hire should not discover the registry on day three when CI works and local pull fails.
Artikals is for this because DEV and Medium are full of “how we structure our monorepo” from teams that also forgot the README. Be the person who writes the paragraph. Future you is a new hire again, on a different repo, in two years.
