The Why Ledger
You will never out-document your tenant. Stop trying. Write down the decisions instead.
tldr;
Two weeks ago the Bus Factor post said: you documented the what, and the why is still in your head. This is where the why goes instead.
Not a wiki. Not a documentation project. A ledger: four lines per decision, three minutes, written the day the decision happens.
The test for what earns an entry: if you’d have to explain it twice, it’s an entry.
The format: Date. Decision. Why. What we rejected. (Landmine, optional but recommended.)
The first copy of the why goes in the object’s own notes field (yes, the ones sitting blank in your tenant right now). The ledger is the commit log.
The audience is Month-14 you, audit-season you, your eventual successor, and the AI you will one day point at your tenant. In roughly that order.
I was dealing with an issue a few years ago that I want you to sit with: why does the offer approval route through a comp partner when the requisition is flagged remote? An HR Partner complained that it was a “useless routing step”.
Nobody knew.
So we did what every HRIS team does. Archaeology. Dug through old tickets. Searched Temas back three years. Found a thread that referenced a meeting that referenced a decision made by someone who left in 2019 (no notes, obviously, the meeting was the notes).
And then we did the other thing every HRIS team does. We kept the step. Because deleting a rule you don’t understand is scarier than living with one you can’t explain.
That’s how tenants calcify. Not through bad decisions. Through good decisions that outlived their reasons.
You cannot out-document the tenant
I know what the responsible voice in your head said after you ran the Bus Factor audit. “We need a documentation initiative.” Runbooks. A config workbook refresh. A wiki with a taxonomy and an owner and a quarterly review cadence.
Don’t.
I said it two weeks ago and I’ll say it harder now: a wiki nobody reads is just guilt with a URL. What-documentation is a photograph of a moving system. It’s stale the first time a release touches the config, which is to say, immediately. You will spend forty hours building it, feel wonderful for a month, and then it will depreciate in exactly the way the knowledge in your head does, except now there are two things rotting instead of one.
The problem was never the what. The tenant will tell anyone the what (that’s what a tenant is). The thing that dies when someone leaves is the why. And the why has a property that the what doesn’t:
The why never changes.
A decision happened once, on a specific day, for specific reasons, with specific alternatives on the table. That’s history. History doesn’t go stale. Which means you don’t document the system (unwinnable). You document the decisions (four lines, done forever).
The ledger
Here’s the entire practice. A running log, one place, append-only. Every entry:
DATE: 2026-03-11
DECISION: Comp eligibility rule excludes interns
WHY: 2019 acquisition brought 400 interns on a stipend structure that breaks the merit matrix
REJECTED: Separate comp plan (Finance refused the headcount)
LANDMINE: The intern flag feeds the benefits eligibility integration. Touch one, test the other.
That’s it. That entry takes three minutes to write and it just answered every question your successor, your auditor, and your own confused future self will ever ask about that rule. The Bus Factor post used this exact example as the knowledge trapped in your head. Now it’s trapped in a text file instead. Progress.
What earns an entry? Simple test: if you’d have to explain it twice, it’s an entry. The weird BP step. The security group shaped like a question mark. The integration you modified instead of replaced with an orchestration. The report you built because the delivered one lies. Anything where the config makes sense only if you were in the room.
Write it where the body is buried
Workday gave you a notes field on almost everything. Business process definitions have comments. Calc fields have descriptions. Condition rules, custom reports, integrations, security groups. Copious fields, shipped with the product, sitting blank in every tenant I have ever touched.
So the first copy of the why goes on the object itself. Paste the WHY line (dated) straight into the calc field description, the BP comment, the condition rule notes. Your successor doesn’t find it by knowing your ledger exists. They find it by opening the thing that confused them, which is the only place you can guarantee they’ll look.
Engineers figured this out fifty years ago: comments live in the code, history lives in the commit log. The note on the object is the comment. The ledger is the commit log. You want both, and here’s why the ledger doesn’t collapse into the notes fields:
Notes hold current state. People overwrite them. The reversals, the rejected alternatives, the story of how you got here: that’s the log’s job.
Cross-object decisions are homeless. The offer-routing decision touches a BP, an integration, and a security group. Which object gets the note? All three get a pointer. The decision itself lives in the ledger.
You can’t grep the tenant. Aggregating every comment field across every object type into one view is not a delivered experience. Your ledger is searchable today, from your phone, in one keystroke.
And this is where the robot argument gets teeth. When you eventually point an AI at your tenant, a dated why sitting in the object’s own description is context the model cannot miss. You’re not just keeping receipts anymore. You’re annotating the substrate.
The rules that keep it alive
Every documentation initiative you’ve ever watched die was killed by ceremony. So the ledger has exactly five rules, and four of them are about staying small.
Write it the day the decision happens. The why has a half-life of about a week. By Friday it’s fuzzy. By month three it’s vibes. By month fourteen it’s archaeology.
Two copies, both cheap. The why goes on the object, dated. The full entry goes in the ledger, which lives in one place (a doc, a channel, a text file; searchable beats structured). Thirty extra seconds. Worth it every time.
Three minutes, max. If an entry takes longer, you’re writing documentation again. Stop. Four lines. If it takes more than three minutes you will quit by August, and I’d rather have a scrappy ledger you keep than a beautiful one you abandoned.
No template committee. The moment this gets a SharePoint taxonomy, a review workflow, and a governance owner, it dies. It’s a ledger, not a program. Protect it from process the way you’d protect anything you actually need.
Append, don’t edit. When a decision gets reversed, that’s a new entry with its own why. Now you have the one thing no config workbook on earth contains: the story of how you got here.
Who you’re actually writing it for
Month-14 you. Seena Mojahedi’s framing from the last post: the SI leaves what-documentation because that’s what the SOW pays for, and around month fourteen something changes that nobody internal has the why for. The ledger is the thing the SOW never buys. Write it yourself, in real time, and Month 14 becomes a Tuesday.
Audit-season you. “Why is this configured this way” is the entire genre of auditor questions. Watching someone answer from a dated ledger entry instead of a shrug changes the temperature of the whole engagement.
Your successor. Someday there is one. The what they can read in the tenant. The ledger is the only artifact that makes them competent instead of merely credentialed.
And the robot. This is the part I need this audience to hear: sooner or later you are going to point an AI at your tenant. When that happens, the model will read your configuration fluently and explain it confidently, and without the why, some of what it confidently explains will be wrong (the config shows the intern exclusion; it does not show the acquisition, the stipend structure, or Finance saying no). Your ledger is the context layer. It’s the difference between an agent that knows why the rule exists and one that hallucinates a plausible reason and routes work accordingly. Clean your data before you buy the robot, yes. But also: keep your receipts, because the robot is going to ask.
Start with the audit
You don’t need to backfill a decade. You’ll never do it and the guilt will kill the habit.
Take the three or four spots the Bus Factor audit flagged (the ones where the honest answer to “who else knows this?” was nobody) and write those entries this week. From memory, dated today, flagged as reconstructed. Then keep the ledger going forward, three minutes at a time.
Your tenant is a decade of business decisions wearing a software costume.
Start keeping the receipts.
— Mike
Director HR Tech | Tenant Archaeologist
P.S. Justin keeps a log in Justin’s 3D Lab. Not of printer settings (the printer knows the settings). Of failures: what got messy, what he changed, why the fix worked. I asked him why he bothers. He said, “because I already printed the same mistake twice, and filament costs money.” A twelve-year-old independently derived the why ledger the second time a failure got expensive. Most of us are still waiting for the third or fourth.
The Department of First Things First. For the people who do the work.