Onboarding onto a legacy product in two weeks
Day one. Someone gives you a login to an internal wiki with 400 pages, most last edited in 2021. The product has eleven modules, four of which nobody on the current team built. Your manager says "take your time, ask anything", then goes into meetings for a week.
Two weeks later you are expected to have opinions. The gap between those two moments is where most new QA hires quietly panic.
You do not need the whole system. You need the money path, the right people to ask, and one good bug. That is achievable in ten working days.
Short version
- Follow the money first. Learn the flow that generates revenue before anything else.
- Read the bug tracker before the wiki. It is current, the wiki is not.
- Find three people: the historian, the current owner, and the support voice.
- Do not try to fix the process in week one. Learn why it is that way.
- Aim for one well-reported real bug by day seven. It buys you credibility.
Why legacy products need a different approach
A legacy product has documentation that describes a version which shipped years ago. If you learn it as written, you will repeat things that are no longer true and lose trust doing it.
Three assumptions to drop:
- The wiki is accurate. Treat it as history. Check anything important against the running system.
- Somebody understands the whole thing. Usually two or three people each know a slice, and one person who knew the rest has left.
- Odd behaviour is a bug. In legacy systems, odd behaviour is often a deliberate fix for a customer problem from 2019. Ask before filing.
Week 1: get oriented
Day 1 — Access and the map
Spend the day getting unblocked, not learning. Chase every credential now, because each one takes a day to arrive.
Your access checklist:
- Staging and production URLs, plus test accounts for each role, such as
[email protected]and[email protected]. - The bug tracker, with permission to create and edit tickets.
- Read access to the code repository and the test management tool.
- The logging tool. Ask which one shows production errors.
- The team chat channels, including support and on-call.
Then draw a one-page map of the product: the main modules, and which team owns each. It will be wrong. Show it to someone on day 2 and let them correct it. A wrong map that gets corrected teaches faster than a right map you were handed.
Day 2 — Follow the money
Find the flow that makes the company money and walk it end to end as a real user. For a shop that is browse, add to cart, pay, confirm. For a SaaS product it is sign up, invite a team, upgrade a plan.
Do it slowly, with Chrome DevTools open. Watch the network requests. Note every screen, every email, and every place the flow could be interrupted. Write down what you did not understand, because that list is your interview script for day 4.
Day 3 — Read the bug tracker, not the wiki
The tracker is the most honest document in the company. Do four searches:
- Bugs closed in the last 90 days. This is what actually breaks.
- Bugs reopened more than once. These mark fragile areas.
- Open bugs older than a year. These show what the team lives with.
- Critical or blocker tickets from the last year. These show what "serious" means here.
Read the comments, not just the titles. The argument in the comments tells you how decisions get made and who has the final word.
Day 4 — Talk to three people
Book 30 minutes with each. Say up front that you are new and want their view, not a training session.
The historian. The longest-serving engineer or support person. Ask: which part of this system scares you? What breaks every release? What did we build that nobody uses?
The current owner. The product manager or lead for the area you will test. Ask: what is the next release? What are customers complaining about? If we could only test three things before shipping, what would they be?
The support voice. Whoever answers customer tickets, and the most underused person in QA onboarding. Ask: what do users report every week? What workaround do you give them? These answers are real, reproducible failures, and they are where your first bug will probably come from.
Day 5 — Set up your environment properly
Get to the point where you can test without asking anyone for help.
- Make sure you can reset your test data yourself. If you cannot, find out who can and how long it takes.
- Learn how to tell which version is deployed to staging. Look for a build number in the footer or a
/healthendpoint. - Find the log viewer and search it for an error you caused on purpose.
- Note the feature flags in use. In legacy systems, flags explain a large share of "it works for me" arguments.
Week 2: find something real
Day 6 — Charter your first exploratory session
Take one high-risk area from your day 3 and day 4 notes. Give yourself 90 minutes and a written mission.
Charter: Explore the invoice export with date ranges that cross a month boundary, an account with 0 invoices, and an account with 500+, looking for wrong totals or timeouts. Staging,
[email protected]. 90 minutes.
Legacy systems reward this kind of testing, because the edges were built by people who left and were never revisited. Attack boundaries: empty states, very large states, deleted users, and anything created before a known migration.
Day 7 — File your first bug, carefully
Your first bug report is read more closely than any other you will write. It sets your reputation.
Before filing, do three things:
- Reproduce it twice, once on a fresh session.
- Search the tracker using the error text, not your own wording. Legacy products have long memories, and a duplicate is a weak first impression.
- Ask one person whether it is known behaviour. Phrase it as a question: "Is the export meant to exclude cancelled invoices? I am seeing that on staging."
Then write it in full: title, numbered steps, expected, actual, environment, evidence. Include the console error as text, such as TypeError: Cannot read properties of undefined (reading 'total'), and the failing request with its status code. Collecting that by hand is slow, which is why many teams report from the page with a browser tool like Crosscheck that attaches the screenshot, console log, network requests, and environment details automatically.
A good first bug is not the biggest bug. It is the clearest one.
Day 8 — Learn the release process
Sit with whoever runs the release, or watch a recording of the last one. You are answering four questions:
- What is checked before a release goes out, and by whom?
- How long does the check take?
- How does a release get rolled back, and how often has that happened?
- What has escaped to production in the last six months?
Write the answers down. Nobody else on the team will have them in one place.
Day 9 — Write what did not exist
Pick the smallest useful gap and fill it. Not a strategy document. Something someone uses this month. Good candidates: a corrected map of the modules and their owners, a smoke checklist for after each deployment, or a test data recipe listing the exact steps to create an account in each state.
The test data recipe is usually the winner. On legacy products, setting up data is the slowest part of testing, and a written recipe saves everyone time immediately.
Day 10 — Present what you found
Ask for 20 minutes with your manager and the team. Cover four things: what you tested and found, the three areas you think carry the most risk with a reason for each, two questions you still cannot answer, and one small thing you would like to change.
Keep that change small. "Add the build number to the staging footer" gets agreed on the spot. "Replace the test management tool" does not, and it makes you sound like you have not understood the constraints yet.
What to avoid in the first two weeks
| Tempting | Why it backfires | Do instead |
|---|---|---|
| Rewriting the test suite | You do not yet know which cases earn their place | Read them, mark the ones that look stale, wait |
| Filing 30 minor cosmetic bugs | Reads as noise and hides your good findings | File 1 to 3 real bugs, well written |
| Saying "at my last company we..." | Legacy constraints are invisible to newcomers | Ask why it is done this way, then decide |
| Learning every module | You end up knowing a little about everything | Go deep on the money path first |
| Waiting to be given work | Nobody has a spare hour to plan yours | Bring a charter and ask if it is worth doing |
After two weeks
You should be able to walk the main flow without notes, name the three riskiest areas, know who to ask about each module, and have one bug and one written artefact to your name.
That is enough. Depth in the other modules comes over the next two months, one release at a time. What you cannot get back is the first two weeks, when asking basic questions costs nothing.
Frequently asked questions
What if there is no documentation at all?
That is common and survivable. The bug tracker, the support inbox, and the release history give you everything the wiki would have, and they are current.
How many questions is too many?
Batch them. Keep a running list and bring five to a 30-minute session instead of sending five separate messages. That respects people's time and gets better answers.
Should I read the source code as a QA engineer?
Read it to answer specific questions: which fields a form sends, what a validation rule allows. Do not read it to learn the system. It is too slow, and legacy code lies about intent.
What if my manager gives me no onboarding plan?
Use this one and share it with them on day one. Most managers are relieved when a new hire brings a plan, and it gives them something concrete to correct.
Is two weeks enough for a large enterprise product?
Two weeks is enough for one product area, not for eleven modules. Agree with your manager which area you own first, and treat the rest as later work.
Add to Chrome