DATA CULTURE
Nobody reads the data dictionary, so we changed where it lives
Documentation that sits outside the workflow is documentation that does not exist.
Daniel Okafor
Data
A wiki page is where definitions go to die
We maintained a careful, thorough data dictionary for two years. It was accurate, well organised, and consulted by approximately nobody. People asked in chat instead, got an answer from whoever replied first, and moved on with a slightly wrong definition.
So we moved the definitions into the tools people already had open — surfaced on hover in the dashboard, attached to the column in the warehouse, printed in the query results. Usage did not need to be encouraged, because there was no longer anything to remember.
The maintenance question
Embedded documentation only stays true if updating it is part of changing the thing it describes. We tie definition changes to the same review that changes the underlying model. If the two drift apart, the build complains.
