← Atlas

An architecture guide is only useful while it is still true.

This is how Atlas is built and how it stays current — written for the people who will be asked to defend what comes out of it.

A drawing decays quietly. Nothing on the page changes, nothing raises an alarm, and the first person to discover it is usually a client. The method below exists to make that decay visible on the day it happens rather than the day it embarrasses someone.

  • 12published sources under watch
  • 14classes of change we look for
  • 4evidence states, and no fifth
  • 1rule above all others: quote, never paraphrase
01Why this exists

Nobody's Maximo architecture went out of date on purpose.

Every stale drawing on every wall was accurate when it was drawn, reviewed by competent people, and approved. It went out of date because the ground moved underneath it and the document had no way of noticing.

Three things move that ground, and none of them announce themselves to the people holding the drawing.

  • The release cadence.IBM ships continuously. Products gain capabilities, change their prerequisites, and pick up new deployment shapes between one release and the next — and a drawing approved against 9.0 is silently describing a system that no longer exists at 9.2.
  • Lifecycle dates.Support windows close on a published schedule that almost nobody re-reads. A release that was perfectly reasonable at design time can be on extended support by the time the programme actually delivers.
  • Renaming and repackaging.The most expensive kind. A product that was licensed standalone becomes an add-on inside another one; a name changes; a capability moves between bundles. The box on the diagram still says the old thing, and the commercial case underneath it has quietly stopped adding up.

The result is a document that everybody keeps using and nobody quite trusts. It gets re-verified by hand before each big meeting, by whoever is free, from whatever they can find — which is exactly the work this method is meant to stop repeating.

02What living means

Not a document that gets updated. A record where every claim knows where it came from.

The difference sounds academic until the first time somebody challenges a figure in a design review.

A document that gets updated quarterly is still, on any given day, a set of unattributed assertions. You cannot tell which sentences were checked last week and which have been copied forward since 2023, because they look identical on the page. Updating it means re-reading the whole thing, so in practice it does not get updated — it gets replaced, eventually, by somebody with a spare fortnight.

Atlas is built the other way round. There is no document. There is a set of records, and each one carries the sentence that supports it, the page that sentence came from, the date it was read, and a fingerprint of the text as it read that day. A drawing is generated from those records rather than maintained alongside them, so the drawing cannot be more confident than the evidence underneath it.

That single change is what makes currency tractable. Re-verifying a document means reading all of it. Re-verifying a record set means re-reading the sources and seeing which fingerprints stopped matching — which is a much smaller job, and one that can be done on a schedule rather than on a deadline.

03What counts

Where the facts are allowed to come from.

Sources are classed, and the class decides what a source is permitted to settle. This is the part that stops a confident blog post becoming a compatibility guarantee.

  • Product documentationIBM's own technical and deployment documentation. Permitted to settle anything it states directly.
  • Release notesWhat changed in a named release. The primary source for deprecation, renaming and repackaging.
  • Licensing materialWhat is included, what is separate, what consumes entitlement. Never inferred from a product page.
  • Lifecycle and supportPublished end-of-support and extended-support dates. The only acceptable basis for a dated warning.
  • The releases indexIBM's published build list. The basis for fix-pack resolution on the MAS line.
  • Everything elseConference talks, practitioner posts, forum answers. May raise a question worth investigating. May never settle one.

The catalogue currently holds twelve sources under watch. That number is deliberately small: a source that is watched properly is worth more than ten that are cited once and never revisited.

04How a claim enters

From a published page to a box on a drawing.

  1. The page is captured

    The source is fetched and reduced to text. This is the only step that touches the network, and it happens when the catalogue is built — never while somebody is using Atlas.

  2. A sentence is taken verbatim

    Not summarised, not paraphrased, not tidied up. If IBM's wording is awkward, the awkward wording is what gets stored, because a paraphrase is an opinion wearing a quotation's clothes.

  3. The excerpt is fingerprinted

    The exact text is hashed and stored with the record. From then on, every build re-checks that the sentence still reads the way it did. A page that is quietly re-published cannot stay quietly quoted.

  4. The claim is bound and stated

    The record is attached to what it supports — an element, a relationship, a constraint — and given one of four evidence states. Nothing reaches a drawing without one.

  5. The build refuses bad records

    A claim missing a source, a state, or a matching excerpt does not degrade gracefully into a slightly weaker claim. It stops the catalogue from being published at all.

05The states?

Four states, and strict rules about what may move between them.

The states are not a confidence score. They describe the kind of thing a claim is, and a claim cannot be promoted by being useful, popular or convenient.

  • Only a source can make something documented.Not a strong argument, not a consultant's certainty, and not the fact that everybody knows it. If no captured page says it, the record is inferred and reads as inferred everywhere it appears.
  • What a customer tells you never becomes an IBM fact.Customer-declared records are recorded, drawn and used in the reading — and can never move any other record's state, no matter how many estates declare the same thing. Popularity is not evidence.
  • Inferred records must show their working.An inferred claim carries what was searched and what was found, so a reviewer can check the same pages and disagree with the specific judgement rather than with the tool in general.
  • A gap is drawn, not omitted.Where we do not know, the drawing says so. An element quietly left off reads to every reviewer as one that was considered and ruled out, which is a claim we have not earned.
  • There is no fifth state.Material found near a claim but not backing it stays near it. Creating a comfortable middle state would let weak evidence migrate upward one small step at a time, and the whole record set would lose its meaning within a year.
06Staying current

How the record is kept alive.

Currency is a loop, not a release. Each pass re-reads the watched sources, compares them to what was stored, and turns the differences into work for a human.

  1. Re-read the watch list

    Every watched source is fetched again and reduced to text the same way it was the first time, so any difference is a real difference rather than a formatting artefact.

  2. Compare, and mostly do nothing

    An unchanged page costs nothing and produces nothing. This matters more than it sounds: a loop that generates noise on every pass is a loop people stop reading within a month.

  3. Classify what did change

    Changes are sorted into fourteen classes — a lifecycle date moving, a product being deprecated, a rename, a licensing change, a prerequisite shifting, and so on. The class decides how urgent it is and who needs to see it.

  4. Re-check the claim, not just the page

    The rule that does the most work here: a page that changed is not evidence that a claim changed. Pages are edited constantly for reasons that have nothing to do with us. The excerpt behind the affected claim is re-checked specifically before anything moves.

  5. A person decides

    Nothing promotes, demotes or retires itself. A candidate change is reviewed and either applied with its new evidence or dismissed with a reason — and the record keeps both.

  6. The archive keeps the old reading

    Every pass appends what each claim's evidence looked like that day. That archive is what lets Atlas answer the question a customer actually has: not what is true now, but what has changed since I last looked.

Part of the loopWhat it doesToday
CaptureFetch each watched source and reduce it to comparable text.Mechanised
Excerpt checkRe-verify every stored quotation against the page it came from.Mechanised
ValidationRefuse to publish a catalogue where any record is missing its source or state.Mechanised
Change archiveAppend what each claim's evidence looked like on this pass.Mechanised
ScheduleRun the loop on a calendar rather than when a person starts it.On the roadmap
Review queueTrack candidates raised against candidates cleared, so a backlog is visible.On the roadmap

We would rather tell you which half is automated than imply all of it is. The capture and verification are mechanical today and run on every build; putting the loop on a schedule, and measuring whether the review queue drains faster than it fills, is the next piece of work rather than a shipped feature.

07Using it

Where this fits in the way you already work.

The method is only worth anything if it survives contact with a real engagement calendar. Four moments do most of the work.

  • At handoverRecord the estate once, properly. Everything after this is comparison rather than discovery.
  • Before a design reviewRe-open the estate and read what moved. This is the meeting where a stale fact costs the most.
  • While drafting a proposalGenerate from the record rather than from memory, so every claim arrives with its source attached.
  • At each milestoneExport the estate as a file and keep it with the design documents. A record you can re-open is a record you can defend.
08Limits

What the method cannot do, stated plainly.

  • It cannot cover what IBM does not publish.Where a question has no published answer, the record says so and stays a gap. We will not fill it with a reasonable-sounding sentence.
  • It does not read your systems.No agent, no connector, no scraping a production Maximo. An estate is what a person recorded, and it stays marked as that person's word.
  • It does not resolve fix packs on the classic line.7.6.1.x builds publish through a different process than the MAS releases index. Atlas reports that it did not look, rather than reporting those builds absent.
  • It will not make the recommendation.The method assembles evidence and marks the judgement calls. What to advise depends on appetite, timeline and budget, and none of those live in a catalogue.
09Next

Bring one customer. We will read their estate with you.

The method is easiest to judge against an estate you already know well — including the parts where it tells you it does not know.

Start a conversation