1. Institutional Business and Data Glossary (Data Cookbook)
  2. How to Document a Specification in Data Cookbook

How to Document a Specification in Data Cookbook

What to Document with a Specification

Sample types of data objects to document with a specification:

  • Cognos or Tableau report
  • Data feed
  • Excel spreadsheet
  • ETL process
  • Cognos package

As a best practice, include a specification every time you share a data object.

Your intended audience is the typical consumer of your data object. Use as much or as little information as you think he/she would need to understand the data object.

Why Document a Specification?

  • Recording the purpose, description, and structure of a data object enables others to quickly understand the object
  • Allows others to self-serve in understanding an object – reducing email and training
  • Makes it easy to re-use data objects. Re-use encourages consistency and faster development of future data objects.

Verify Access Levels for Your Data Cookbook Account

You will need these access levels to create a Specification:

  • To view your access levels: Under the Organization tab > Users > your name. Contact Cynthia Carlton to change your access levels.
  • Reporting Role = Worker. Without the Worker role status you will not see “Create a Specification” under the Specifications Tab.
  • Functional Area Role = Editor or Moderator for each Functional Area containing terms for the specification you are documenting.

Get Started in Data Cookbook

  1. Login to Data Cookbook with your NetID.
  2. Click Specifications > Create a Specification
  3. Complete the fields, note required ones. You can edit all of this content later.
    • Name – make it identical with the item you are cataloging
    • Specification type – choose one
    • Functional Area – choose one
    • Purpose – why does this item exist? What decisions are made based on the content? Who makes them? How often
    • Description – Describe the physical characteristics of the item. What does it look like? What does it contain?
  4. Assign to yourself or another staff person.

Record Metadata

Record metadata in the 8 tabs in the Create a Specification process.

Data Cookbook tabs

Overview Tab

  • Click Edit to revise content entered at the Create A Specification step.
  • Purpose: Why does this item exist? What decisions are made based on the content? Who makes them? How often?
  • Description: Enter a brief description of the physical characteristics of the item.
  • Owner: Use job titles or department instead of personal name.
  • Data System: Select one or contact Cynthia Carlton to add yours.
  • Specification type: Select one or contact Cynthia Carlton to add yours.
  • Access details: Provide URL to application form or directly to report if public. Describe who qualifies for access.
  • Additional details: An optional field. Some specification writers use it as a scratch pad to keep track of things they want to treat include but have not yet decided how to treat. The notes can be deleted as they are addressed in the specification.

Definitions Tab

  • Add and associate definitions. Create new definitions as needed.
  • Reference box: Enter the name of the definition as it appears in the data object if different from the approved Name in Data Cookbook.
  • Click the question mark icon for instructions for the remaining fields.

Selections (or Filters) Tab

  • This area records pre-search filters. What does the user enter in the search screen to retrieve the data within the specification?
  • Use Definitions as filters or describe the filters in the Description.
  • Note instructions under the question mark icons.
  • Use multiple Selection Sets to document complex filters.
  • Some Specifications don’t have filters.

Sort Criteria Tab

  • Record the terms used to sort data within the report.
  • Some Specifications don’t have sort criteria.

Technical Tab

  • Identify the Data System that provides the data. Only one system can be recorded.
  • Once the Data System is selected, the corresponding technical definition that matches that data system will automatically populate the Specification. If a term does not have a technical definition for that data system, a wrench icon appears next to the Definition in the definition list under the Definitions tab. Provide a technical definition for each wrench icon.

Display Details Tab

  • Use judgment in the level of detail recorded on this tab. All Display Details fields are optional.
  • Output description. Use complete sentences to describe the output. For example, for data feeds include the file format.
  • Specification type – choose one. Contact Cynthia Carlton to add a new type.
  • Header – describe the header.
  • Display layout – describe the body of the specification or report.
  • Footer – describe the footer.

Attachments Tab

  • Attach a file to the specification. This is optional.
  • The attachment can be a page of a report or other visual of the actual specification.
  • Attachments can be viewed by all users. Avoid posting documents that contain sensitive information.

Collaboration Tab

  • Use fields on this tab to request testing, approval, or other input.

Samples

These sample specifications are especially well written. Refer to these if you are new to writing specifications.

  • Sponsored Projects – Award Detail Report
  • Any of the Cumsal reports
  • Provost All Faculty Distribution List