Over two years 11 of 18 funded data stewards changed role. The glossary is current and accurate. But when an analyst asks why completed order excludes partially refunded orders, nobody can say why, and the question is re-argued every quarter by new people. Design the record a stewardship decision has to leave behind.

Requirements that drive the structure

The glossary stores the current state. Stewardship produces decisions, and a decision carries information the current state throws away: what was asked, what else was considered, why it lost, and from when the ruling applies. Turnover is the normal case, not the exception - at a 20% annual move rate, half a steward group has changed inside three years - so the design target is that a ruling survives the person who made it without a handover conversation.

The design

One append-only record per ruling, six fields:

1. The question as asked, in the asker's words. This is what makes the record findable later, because the next person asks it the same way.
2. The ruling, in one sentence, plus the expression it changed.
3. The rejected option and why. The field that does the work. "Include partial refunds, so the number ties to the payments ledger; rejected because operations uses completed order to plan dispatch and a refunded order was still dispatched."
4. Effective from, as a date, and whether history was restated.
5. Who decided, by role as well as name.
6. Affected datasets and reports, generated from lineage rather than typed.

Store it next to the definition's code - a dated block in the model file, or rows in a small table the catalogue renders. Not in meeting minutes: minutes are organised by date, and nobody searches by date.

The hard part

Getting the rejected option written down. It is the only field that prevents re-litigation and the only one that feels like extra work at the time, because the author has just finished believing their own answer. Make it a required field in the template and keep the whole record under 150 words, which is about five minutes.

Second hard part: putting the ruling where the argument happens. A record nobody reads is cheaper to delete than to maintain. Link it from the glossary entry, from the column description the BI tool shows on hover, and from the comment header of the model that implements it.

What it costs

Roughly one ruling per contested term per 18 months. With 25 genuinely contested terms that is about 17 rulings a year and under two hours of writing - trivial. The real cost is the discipline to refuse a ruling that nobody will record, which means the steward sometimes has to say "I will answer this on Thursday in writing" to someone who wanted an answer in chat.

How it fails

• It becomes a write-only log. Detect this: how many rulings were opened from a glossary page in the last quarter? Zero means you have an archive, not a record.
• Rulings without effective dates, so a report rerun for last year silently uses this year's meaning and nobody can tell whether a historical restatement happened.
• Rulings recorded by the platform team on the steward's behalf, which shifts authorship and with it accountability.

When this is over-engineering

Below roughly 25 contested terms and one data team, a dated comment block in the transformation code is the entire mechanism and a separate register is bureaucracy. The signal that you have outgrown it: the same definition question reaching a steward twice from different teams. One recurrence is noise; two is a missing record.