How to Read a New Team's Documentation Without Believing All of It

Read a new team’s documentation in a fixed order (system context, interface contracts, external usage guidelines, runbooks, incident postmortems, the backlog, the test suite) and keep a trust register while you do. Every internal page is a claim about the system, dated the day it was last edited. Rate each page, verify the claims your work depends on against code, logs, and data, and treat postmortems and the code as the most honest documents the team owns.

In week two of a new job you will be pointed at a Confluence space with several hundred pages and told “everything is in there.” Some of it is. Some of it was true two years ago. Some of it describes a design that was approved and then quietly changed during build. And some of it was written by a contractor who left before go live, and nobody has opened it since.

This is part 2 of The First 90 Days, a series on succeeding in a new company or team as a technical analyst. Part 1 laid out the four phase plan. This part covers the documentation lever in depth: what to read, in what order, and how to decide what to believe. Part 3 then shows how to use AI to read faster without inheriting the same errors.

Why can’t you just read all the documentation?

Because volume is not the problem. Reliability is.

A new analyst who reads every page uncritically ends up with a confident, detailed, wrong model of the system. Worse, that model leaks into the first specification they write, with a field name that was renamed, a status that no longer exists, or a business rule the code stopped enforcing a year ago. The developer reviewing it knows immediately, and the new analyst’s credibility takes a hit that is hard to recover in the first month.

Documentation drifts for structural reasons, not because teams are careless. Pages are written at design time and code changes at build time. Incident fixes change behavior without anyone updating the functional specification. External standards publish new releases annually. People who knew the reason for a rule leave. Every page you read is a snapshot of someone’s understanding on the day they last edited it.

So the goal is not to read everything. It is to read the right things in the right order and build an explicit, written opinion of how far each one can be trusted.

In what order should you read a new team’s documentation?

From the widest view to the most concrete evidence. Each layer corrects the one before it.

Order	What to read	What it tells you	How much to trust it
1	System context and architecture overview	Which systems exist and how they connect	Usually right about boxes, often wrong about arrows
2	Interface contracts: OpenAPI files, XSDs, message specs, event schemas	What each system promises to send and accept	High if generated from code or validated in CI
3	External usage guidelines and standards	What the outside world requires	High: published, versioned, owned externally
4	Runbooks and operational procedures	What happens when things go wrong, in practice	Medium to high: operations update them because they use them
5	Incident postmortems	Where the system proved the other pages wrong	Very high: written after the fact, with evidence
6	The backlog: open epics, recent tickets, open defects	What is changing now and what is broken	High for what it says, low for what it omits
7	The test suite	What the team actually checks	Very high: tests fail when they are wrong

Notice where the functional specifications and requirements pages are: nowhere on the list as a primary source. Read them, but read them through the lens of the other seven. A functional specification tells you what was intended. The contracts, the postmortems, and the tests tell you what is.

Start with the system context, but distrust the arrows

The architecture overview gives you the vocabulary of system names. Learn them. But treat every arrow as a claim to verify. Diagrams rarely show retries, asynchronous callbacks, batch files, or the manual step where operations rekeys something into a second system. System context diagrams explains what a good one should show, which helps you spot what yours omits.

Read the contracts before the specifications

An OpenAPI file, an XSD, or an event schema is the closest thing to a promise the system makes. If it is generated from code or validated in a pipeline, it is probably accurate. If it is a Word document attached to a Confluence page, check its date. Reading an API contract covers how to read one properly.

Read the postmortems early

This is the single most underused onboarding tactic. A team’s incident postmortems are a list of the places where reality disagreed with the documentation, written by people who had to explain it to management. In a payments team, a year of postmortems will tell you about the duplicate payment that slipped past idempotency, the batch that ran twice, the correspondent that rejected a whole day of messages over a field format, and the cut off time that was wrong in every document. You will learn more about the system’s real behavior in two hours of postmortems than in two weeks of specifications.

What is a documentation trust register?

It is a table you keep while reading, one row per page or document, that turns reading into analysis. It takes about two minutes per page, and it is the artifact that separates an analyst who read the documentation from one who understood it.

| Page | Owner | Last edited | Key claim | Evidence | Trust |
|------|-------|-------------|-----------|----------|-------|
| Outbound pacs.008 mapping v3 | (left team) | 2024-11 | Town name from CUST_ADDR line 3 | Code reads TOWN_NM column; line 3 fallback only | CONTRADICTED |
| Reason code to customer message | Payments ops lead | 2026-05 | AC04 shows "account closed, contact beneficiary" | Matches template table in DB | VERIFIED |
| Cut off times | Treasury ops | 2026-08 | USD cut off 17:00 New York time | Matches scheduler config | VERIFIED |
| Sanctions screening flow | Compliance IT | 2025-02 | Screening on pacs.008 debtor and creditor only | Postmortem mentions intermediary agent screening added 2025-09 | STALE |
| Return handling | (no owner) | 2023-06 | pacs.004 auto credited to customer | Not checked yet | PLAUSIBLE |

Use four trust levels and define them in the register header:

• VERIFIED. You checked the claim against code, logs, data, a test, or a named owner who confirmed it this month.
• PLAUSIBLE. Nothing contradicts it, but you have not checked. The default for anything you read but have not tested.
• STALE. The page predates a known change to the thing it describes. Probably partly wrong.
• CONTRADICTED. You have evidence the claim is false. Record the evidence.

Two things make the register valuable beyond your own learning. First, the CONTRADICTED and STALE rows are a ready made list of improvements you can propose at your 30 day readout, with evidence attached. Second, when you write your first specification, every claim you reuse from documentation has a trust level, so you know which ones to double check.

If you want templates for the deliverables you will eventually write on top of this, Real-World BA Deliverables has twenty of them, including the specification and mapping formats used on banking programmes.

A real example: the reason code page that disagreed with the code

On one programme I joined, a cross-border payments team had a Confluence page titled “pacs.002 rejection handling.” It was well written, had a clear table, and was the first result for every search about rejections. It said that when an outbound pacs.008 came back as a pacs.002 with transaction status RJCT and reason code AC04 (closed account), the customer would see a message saying the beneficiary account was closed and the payment had been returned, with funds credited back the same day.

I put it in my trust register as PLAUSIBLE and moved on. Two weeks later, while building my first deliverable (a full reason code mapping table), I traced the actual handling in the code with a developer. The rejection handler did not treat AC04 specially at all. It fell through to a default branch that mapped every reason code without an explicit entry to a generic message: “your payment could not be processed, please contact us.” And it did not credit the funds automatically; it routed the payment to an operations repair queue.

The page had been accurate. Eighteen months earlier, the team had removed the per code handling after a correspondent started sending AC04 for cases that operations needed to review manually, and they changed the code without changing the page. The postmortem for that change existed, and it was linked from nowhere.

Three lessons from that one row:

1. The page was not lying, it was dated. Page history showed the last substantive edit predated the change by four months.
2. The external standard was not the problem. The CBPR+ usage guidelines on SWIFT MyStandards define AC04 clearly. What drifted was the internal “our implementation” page that sat between the standard and the code.
3. The customer impact was real. Customers with a closed beneficiary account were calling the contact centre to ask what “could not be processed” meant, and nobody connected those calls to the page everyone believed.

The row went from PLAUSIBLE to CONTRADICTED, the page was rewritten with the owner, and the full mapping table became my first deliverable. The reason code mapping guide covers how to build that table properly.

Which sources of truth matter in ISO 20022 work?

ISO 20022 payments have a layered documentation stack, and knowing which layer you are reading changes how much you trust it.

Layer	Example	Owned by	Drift risk
The ISO 20022 message definition	pacs.008.001.08 schema	ISO 20022 Registration Authority	Very low, versioned
Market usage guidelines	CBPR+ on SWIFT MyStandards, HVPS+ based scheme rules	SWIFT, market infrastructures	Low, versioned with release notes
Scheme or infrastructure rules	Fedwire Funds ISO 20022 specifications, T2 and CHAPS guidelines, EPC rulebooks	The infrastructure or scheme	Low, versioned
Internal “our implementation” pages	Mapping specification, field population rules	Your team	High
The code and the messages	Message builder, logged XML	Your team	Zero: it is what happens

The external layers are versioned and published. When CBPR+ changed its address rules for November 2026 (structured or hybrid addresses, fully unstructured addresses no longer accepted), the change was announced, dated, and documented. Your internal mapping page was not updated by anyone outside your team.

So in ISO 20022 work there are two reliable anchors: the external usage guidelines and the code that builds the message. Read the internal pages as a translation between them, and verify the translation at the points that matter. The usage guidelines article explains how to read MyStandards properly, and the ISO 20022 reference maps the rest of the domain.

How do you check a page against code, logs, and data?

You do not need to verify everything. Verify the claims your work depends on, using whichever evidence is cheapest to reach.

Against the code. Search the repository for the field name, the status value, or the reason code. A claim like “AC04 is handled specially” is confirmed or refuted by one search for AC04 in the handler. If you cannot read the code fluently yet, ask a developer for fifteen minutes and bring the specific claim. AI in the codebase shows how to get an assistant to trace it with you.

Against the logs. Find a real message in a test environment log. If the page says the town name comes from address line 3 and the logged pacs.008 shows a TwnNm element populated from somewhere else, you have your answer in one minute.

<Cdtr>
  <Nm>MASKED BENEFICIARY</Nm>
  <PstlAdr>
    <TwnNm>Rotterdam</TwnNm>
    <Ctry>NL</Ctry>
    <AdrLine>MASKED LINE 1</AdrLine>
  </PstlAdr>
</Cdtr>

That is a hybrid address: town and country structured, the rest in an address line. If the mapping page claims you send fully unstructured addresses, the log just contradicted it. Reading production logs covers where to find these.

Against the data. A query against a read only replica settles population claims. If a page says every customer record has a structured town name, count the ones that do not:

SELECT channel,
       COUNT(*) AS customers,
       SUM(CASE WHEN town_name IS NULL OR town_name = '' THEN 1 ELSE 0 END) AS missing_town
FROM customer_address
WHERE address_type = 'REGISTERED'
GROUP BY channel
ORDER BY missing_town DESC;

Against a person. When code, logs, and data are out of reach, ask the named owner a specific question with the claim quoted. “Is this still true?” gets a shrug. “The page says AC04 credits the customer automatically; I see repair queue entries for AC04 in the test environment; which is right?” gets an answer.

How do you search Confluence effectively when you are new?

The default search box ranks by relevance, which in practice means old pages with many links win. Use these tactics instead.

Use advanced search with CQL. The Confluence Query Language lets you filter by space, type, label, and date. Some useful queries:

space = PAY AND type = page AND lastmodified >= now("-180d") ORDER BY lastmodified DESC
space = PAY AND text ~ "pacs.002" AND lastmodified < now("-365d")
space = PAY AND label = "postmortem" ORDER BY created DESC
text ~ "PAY-1234"

The first shows what the team actively maintains. The second finds pages about a topic that nobody has touched in a year, which are your stale candidates. The third collects the postmortems if the team labels them. The fourth finds any page that mentions a ticket key, which is how you find the explanation of a change.

Sort the space by recently updated. The pages people edit are the pages people use. A space overview sorted by last modified is a map of where the living documentation is.

Open page history on anything important. The version comparison shows exactly which sections changed and when. A page whose table was edited last month but whose diagram has not changed in three years tells you where to look for drift.

Check who links to it. A page linked from recent Jira tickets is in use. A page linked from nothing is either foundational or forgotten, and you need to know which.

Follow the people, not just the pages. The page author’s profile shows what else they wrote. If one person wrote most of the reliable pages, they are on your stakeholder map. Part 4 covers how to approach them.

If Confluence is a weak spot, Confluence for Business Analysts covers space structure, search, and the habits that keep a wiki current.

Should you fix the documentation while you are new?

Fix it with the owner, not around them, and not in week one.

Your trust register will fill with STALE and CONTRADICTED rows by week three. Resist rewriting pages on your own. Instead:

1. Collect the evidence first. A contradiction with a log line or a query result attached is a fact. A contradiction based on your reading is an opinion.
2. Bring the top three to the owner. “I found three places where the mapping page and the code disagree; here is the evidence for each; would you like me to update the page and send it to you for review?”
3. Present the pattern at your 30 day readout. Not “the documentation is bad,” which every team already knows, but “these five pages are contradicted by evidence, and here is the one change to our process that would have caught it.” Part 5 covers how to frame that.

Done this way, fixing documentation is one of the best first deliverables a new analyst can ship. It is visible, verifiable, useful to the whole team, and it proves you read the system rather than just the wiki.

How should AI fit into reading documentation?

AI can read sixty pages faster than you, list every term, find internal contradictions between pages, and draft the first version of your trust register. What it cannot do is know which page reflects reality, because it has the same pages you do. A model that summarizes a stale page produces a confident, fluent, stale summary.

Use it to find questions, not answers: “list every claim in these pages that two pages state differently,” “list every field name and status value mentioned, with the page it came from,” “which pages describe behavior that a later page or postmortem changes.” Then verify. Use only your organization’s approved tool, and do not paste customer or production data. Part 3 builds this into a full personal knowledge pack. If your company has not approved any AI tool yet, The AI-Powered Analyst covers what you can safely do in the meantime.

The takeaway

Read a new team’s documentation from the widest view to the most concrete evidence: system context, contracts, external guidelines, runbooks, postmortems, backlog, tests. Keep a trust register with an owner, a date, the evidence, and a trust level for every page your work depends on. Verify claims against code, logs, and data before you reuse them, and in ISO 20022 work anchor on the published usage guidelines and the code that builds the message, because the internal pages in between are where drift lives. Fix pages with their owners and bring the pattern to your 30 day readout.

Next, part 3 turns this reading into a personal knowledge pack with AI, and part 4 covers the questions to take to the people behind the pages. The full path is on The First 90 Days. To rehearse the whole thing on a system you have never seen, the Labs give you a contract, events, logs, and a database for a fictional payments platform, where the documentation and the evidence do not always agree.

For the wiki itself, Confluence for Business Analysts covers structure, search, templates, and the review habits that stop pages drifting. Real-World BA Deliverables gives you the specification and mapping formats to rewrite stale pages into. If your organization is cautious about AI, The AI-Powered Analyst shows how to use it on documentation within the rules. And the free downloads include templates you can use from day one.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: Business Analysis, Documentation, Confluence, Onboarding, ISO 20022