Explain what each row represents
Start the dictionary with the dataset’s grain. An order, an order line, and a monthly customer summary are different units even when they share columns. Include a small worked example showing how a real-world event becomes records and which identifiers remain stable across updates.
Document business meaning
For every field, state its definition, type, unit, source, and valid values. Revenue can mean booked, invoiced, or collected amounts; status can describe a workflow rather than a business outcome. Capture these distinctions explicitly. Include timezone and currency conventions beside date and monetary fields.
Make missingness interpretable
Distinguish unknown, withheld, not applicable, not collected, and genuinely zero values wherever the source supports that distinction. Specify reserved codes and blank-string behavior. Buyers should be able to tell whether an empty delivery date indicates an undelivered order or an export that omitted the field.
Version the documentation
Tie the dictionary to a release identifier and provide change notes when fields or categories evolve. Review a representative export against the dictionary before accepting a larger batch. Send Fiund the fields your model actually requires, including allowed transformations and any fields that must be excluded from review. Ask a colleague unfamiliar with the source to interpret five rows using only the dictionary. Have them explain which entity each row represents and what the monetary columns mean. Their unanswered questions provide a practical documentation gap list before the data enters a model or an evaluation workflow for further use.
Review checklist
- State row grain and stable keys
- Define units and category meanings
- Explain every missing-value convention
- Version the dictionary with the release