Body
Data stewards use Data Cookbook to create, review, and approve institutional definitions and specifications. These objects provide a shared understanding of the data, metrics, reports, dashboards, and other information resources used across the University.
Use this guide to create, review, update, approve, or retire a definition or specification.
Definitions and Specifications
Definitions represent words or phrases used at the University, including objects, people, business concepts, measurements, and metrics. Each definition is managed through an approval workflow.
Specifications describe reporting deliverables, such as reports, spreadsheets, dashboards, extracts, database views, or tables in a data store. Specifications are also managed through an approval workflow and support impact analysis.
Data Cookbook sends workflow notifications by email. Check your spam folder and safelist the sender if messages are not arriving.
Create a New Item
- From the Definitions or Specifications menu, select Create a Definition or Create a Specification.
- Complete required fields, marked with red asterisks (*).
- Hover over an information icon (ⓘ) for field-specific guidance.
- Select Save to keep the item as a draft.
- Select Submit to Divisional Review when it is ready for workflow review.
Definition-Specific Guidance
Writing a Strong Definition
Write definitions for someone outside your unit. Use business language rather than system or database terminology.
Include, as relevant:
- A concise explanation of the term.
- Context, intended use, limitations, or common misunderstandings.
- Links to related definitions using double brackets, such as
[[Retention Rate]].
Words in double brackets link to existing definitions in Data Cookbook. Avoid abbreviations unless they are defined on first use. Do not use circular definitions or unnecessary technical detail.
Definition Naming Standards
- Use clear, descriptive names.
- Avoid abbreviations, numbers, and special characters.
- Do not begin a name with “A,” “An,” or “The.”
- Do not use underscores, hyphens, dashes, or ampersands.
- Remove extra spaces before submitting.
Technical and Optional Fields
Complete the Technical Definition fields, including Data System, Time Context, and the technical definition text, when applicable. Use tags only when an existing tag is appropriate.
Contact the data governance team to request new tags, sources, offices, functional areas, or data systems.
Specification-Specific Guidance
Specification Naming Standards
- Use Title Case.
- Do not begin a name with “A,” “An,” or “The.”
- Avoid unnecessary numbers and special characters.
- Remove leading and trailing spaces.
Additional Tabs
Data Items
Use this tab to document the fields or definitions used in the report or dashboard. Select an existing definition when available. Create a new definition if one is needed.
Display
Use this tab, when helpful, to provide a dashboard image, sample attachment, or written description of how data items are presented.
Attachments
Use this tab to add supporting files. Prefer a URL in the specification description when the source is available online. Do not attach a copy of a report or data extract containing actual data.
Technical, AI Analysis, and Sharing
These tabs are not currently in use.
Sidebar Fields
Sidebar fields display after an item has been saved as a draft. Some sidebar fields may also be updated after approval.
Definitions
Synonyms
Use this field for alternate terms, such as abbreviations. A synonym cannot later be used as a definition name.
Related Specifications and Definitions
Use these fields to connect a definition to related specifications or definitions. Select the edit icon, search for the related object, select it, and save the relationship.
Definitions included in a specification’s data items may appear automatically under Related Specifications.
Specifications
Related Specifications
Use this field to connect reports or dashboards that provide related or similar information. Select the edit icon, search for the specification, add it, and save.
Tags
Tags help users filter and find related specifications. Use an existing tag when applicable. Contact the data governance team to request a new tag.
Workflows
Definitions and specifications follow the same four-stage workflow before moving to Approved:
- Drafting – The creator develops the item and may add collaborators.
- Division Review – Divisional Data Management Subcommittee stewards review the item for completeness, accuracy, and adherence to standards.
- Data Management Council (DMC) - Council members review the item for consistency and consensus across divisions.
- DAIR - The data governance team within Data, Analytics, and Institutional Research (DAIR) completes the final, editorial review and approval.
When revisions are needed, select Return to Draft or Return to Division Review and add a comment explaining what needs to be addressed.
Avoid rejecting items. If a definition or specification is no longer needed, contact the data governance team for assistance.
Review and Approval
You can find items awaiting your action through:
- The link in your Data Cookbook notification email
- Search on the Home or Browse Definitions or Specifications page
- My Tasks
- The appropriate approval queue
In the queue, filter by workflow stage, functional area, and items available for action by you.
To review an item:
- Open the definition or specification and select Edit.
- Confirm that the information is accurate, complete, and consistent with standards.
- If more information or revision is needed, add a comment and select Return to Draft or Return to Division Review.
- Make needed edits and select Update.
- Select Submit to DMC or Submit to DAIR to move the item to the next stage.
Editorial Updates
Use the Editorial Update workflow only for minor revisions to an approved definition or specification, such as correcting a typo, adding context, updating a name, or changing contact information.
The workflow has two stages:
- Drafting – Create a new version, make the needed updates, document the reason in the comment field, and select Submit as Editorial Update.
- Editorial Update – DAIR reviews the update, returns it for revision if needed, and approves it.
Collaborators
Collaborators can be added during Drafting, Division Review, or DMC Review for a specific definition or specification.
Available roles include:
- Comment – Can provide comments.
- Edit – Can edit the item.
- Delegate User Role – Has the same workflow role as the current user.
Open Show Workflow, select the collaborator option, and choose the individual and role. Remove collaborators from the same workflow panel when their participation is no longer needed.
Versioning, Retiring, Deleting, and Discarding
Versioning and Updating
When an approved definition or specification needs to be changed, create a new version. Add a comment explaining the change, make the needed updates, and send the new version through the appropriate workflow.
Use Submit as Editorial Update only for minor revisions, such as correcting a typo, adding context, updating a name, or changing contact information. All other changes should follow the standard workflow.
Retiring an Approved Item
When an approved definition or specification is no longer needed, create a new version and use the comment field to explain why it should be retired. Send the item through the standard workflow.
During DAIR review, the item will be moved to the final Retired stage rather than approved. Retired items remain available as an archived record.
Deleting or Discarding a Draft
Use Delete this Definition/Specification or Discard this Version only when a draft or new version was created by mistake.
Do not delete an approved definition or specification. Approved items that should no longer appear in the active list must be retired through the workflow.