Every system we have inherited had some form of audit log. Almost none of them were usable by a non-engineer, which meant the person who most needed to answer "who changed this and when" had to file a support ticket to find out.
The default shape and why it fails
A typical audit table records an actor id, an action string, a timestamp, and a JSON blob of the before-and-after state. Technically complete, practically opaque: a support agent trying to explain a price change to a customer has to be handed a raw database row and decode it themselves.
Design it for the person who will read it
- Plain-language actions — "changed the price from £12.00 to £14.50", not action equals price underscore update with two numbers in a blob.
- Who and on whose behalf — the actor matters, but so does whether they were acting as themselves, as an admin impersonating a user, or as an automated job. Those three cases get confused constantly and matter enormously when something goes wrong.
- A filterable view, not just a table — by record, by actor, by date range, accessible to the support team without a database client.
The case that made us take this seriously
A billing dispute needed us to prove a discount had been applied correctly. The audit table had the answer, technically, in a JSON diff nobody without direct database access could read in under twenty minutes, under time pressure, on a call with an unhappy customer. We rebuilt the log's presentation layer that week, not because the data was wrong but because the data was inaccessible to the people who needed it fastest.
An audit trail nobody can read under time pressure is not really an audit trail. It is evidence that requires an expert witness.
What this costs to build in from the start
Very little, if it is decided early: a human-readable description generated at the point the action happens, when the context is cheapest to capture, rather than reconstructed later from a diff. Retrofitting readable descriptions onto historical rows that only have raw diffs is the expensive version of this problem, and it is the version most teams end up doing.
Where we draw the line
Not every table needs an audit trail. The ones that do are the ones involving money, permissions, or anything a customer might one day dispute — and for those, readability is not a nice-to-have, it is the actual requirement the feature exists to satisfy.