Create a new Assignment Submission Page titled: "A3 - Your Name".  Make sure to tag it with the correct assignment tag ("A1" or "A2", etc). You must do this to ensure that we can see your assignment once you submit it. If you fail to do this or forget to tag your assignment, you may receive a late penalty since we will not be able to find your work.

Assignment 3: Modeling a Vocabulary

Posted: September 20, 2010

Due: October 4, 2010

Author:
Bob Glushko,
 glushko@ischool.berkeley.edu

Lead TA: Kimra McPherson, kimra@ischool.berkeley.edu

Course: Information Organization and Retrieval (INFO 202)


Assignment Overview

In this assignment, you will:

1. Model a vocabulary for describing a restaurant dining experience.

2. Create an instance in XML using your vocabulary. 

3. Swap vocabularies with a classmate. [swap list]

4. Create an instance in XML using your classmate’s vocabulary.

5. Reflect on your vocabulary modeling experience.

Deadline

You must submit your work by creating a new assignment submission page before 9 a.m. on Monday, October 4, 2010. Late assignments will not be accepted unless you have an exceptionally good excuse. Even though you have two weeks for this assignment, you’ll want to start early, as you’ll need to swap vocabularies with a classmate in order to successfully complete all parts of the assignment.

Submission Requirements

You will submit a total of 3 files (zipped), 4 if you submit an optional extra credit file. Name your zipped file YourNameA3.zip (and we know it seems obvious, but make sure YourName is your name, not the words YourName. Yes, it’s happened.)

The first file will be YourNameA3Report.xml, and it should be valid with respect to the Report.dtd document you used in Assignment 2. Edit the “title” attribute in the “Section” element to correspond to the three written parts of this assignment. Your final file should have the following sections:

<Section title=”1. Scoping the vocabulary”>

<Section title=”2. Defining the terms/descriptors”>

<Section title=”3. Reflecting on the vocabulary modeling experience”>

The second file will be an XML instance that contains a sample dining “event” encoded using your vocabulary. Name this file YourNameA3Instance.xml

The third file will be an XML instance that contains a sample dining “event” encoded using your classmate’s vocabulary. Name this file YourNameA3Swapped.xml

You may choose to create a fourth file for extra credit. This file should be a DTD that encodes the model of your vocabulary if and only if your instance is valid with respect to it. If you do this, name the file YourNameA3.dtd and include a document type declaration in your YourNameA3Report.xml file so that we can confirm your instance is valid without having to edit it.

Detailed Instructions

Your task is to develop a vocabulary for describing the experience of dining in a restaurant. As you’ve learned from the first three chapters of IFIOIR and from recent readings on document engineering, modeling a vocabulary involves scoping the problem, making decisions about key trade-offs, choosing meaningful names and descriptions, and being aware of any biases you might be bringing to the vocabulary. This assignment will take you through that process.

Part 1: Scoping the vocabulary

There are many different types of restaurants and many different types of dining experiences. The first thing you must do is settle on a scope for the type of experience you intend to model. Are you looking at five-star restaurants or fast food? Or do you want to try to model a universal dining experience?  

In your report.xml document, under the section title “Scoping the Vocabulary,” write one or two sentences that define the scope of the vocabulary you intend to design. For example, if you were developing a vocabulary for describing course syllabi, you might define its scope by saying, “The Syllabus Vocabulary is a vocabulary for describing a syllabus for a university course. It will describe the topics, readings, assignments, and exams or other important events and the dates associated with each.”

Be sure to carefully consider not only what falls within your scope but also what is outside of it. The Syllabus Vocabulary might want to include some notion of date or time – but making the vocabulary fully compatible with Google Calendar or another calendar format would fall outside the scope.

Part 2: Defining the terms/descriptors

Identify and define the terms and descriptors your vocabulary requires to describe events within your scope. For example, some possible terms in the Syllabus Vocabulary might be Topic, Reading, Date, Instructor, etc.

For each term or descriptor, write a one or two sentence definition. These definitions are your instructions for people using your vocabulary to encode an instance — as your classmate will do later in this assignment — so strive for precision.

Write these terms and descriptors in the “defining the terms/descriptors” section of your report.xml document. To make these definitions easy for us to find and read, write each as a separate paragraph in section 2 of your report (e.g. <Para>Term: Definition … </Para>).

Remember the tradeoffs we’ve discussed so far in the semester. They’ll help you think through some key issues, such as:

• How many “levels” of terms do you want or need? Everything can be at the same hierarchical level, or you may have some terms that are “containers” for others. There’s no right answer; just think about the implications.
• How many terms do you need to cover everything in your scope?
• What are the benefits/drawbacks of a simpler vocabulary? A more complex one?
• Are you being consistent with the levels of abstraction and granularity of your terms?

There’s no required upper or lower boundary on the number of terms that will be in your vocabulary. That said, in the past, we’ve found that a useful vocabulary can be developed with somewhere between 10 and 20 terms.

Part 3: Encoding an instance

You might have developed your vocabulary by thinking of a specific restaurant experience or set of experiences. This step will make that connection explicit, testing your vocabulary by having you create an XML instance of a particular restaurant event.

Encode an instance using your terms in the file YourNameA3Instance.xml. Make sure the instance falls within the scope you defined in step 1. 

As you do this step, you may find you want to change some of your terms, make things less (or more) granular, remove (or add) levels of hierarchy, or alter your vocabulary in other ways. That’s OK! You should revisit steps 1-3 and revise your scope, terms, definitions, and instance as needed. Make some notes on any changes you make – you’ll want them for your reflection later.

If you create an optional DTD (see part 6 for further instructions), make sure your instance is valid with respect to that DTD. If you don’t create a DTD, make sure your instance is well-formed.

Part 4: Swapping vocabularies

Now comes the fun part: You’ll be swapping vocabularies with a classmate in your section. Click here to see the pairings. 

For this part of the assignment, you’ll be sharing parts 1 and 2 of this assignment. DO NOT share your instance, just the scope statement and the definition of terms.

Once you have your classmate’s vocabulary, attempt to encode an instance of their vocabulary using only the scope and definitions they provide. Call your instance YourNameA3Swapped.xml. Again, make sure your instance is well-formed. Send this file back to your classmate.

Part 5: Reflecting on the vocabulary modeling experience

Write a few paragraphs reflecting on your vocabulary modeling experience in your report.xml document under the section “Reflecting on the vocabulary modeling experience.” This doesn’t need to be longer than a few hundred words, but it does need to include, at minimum, the following elements:

(1) Your thoughts on the challenges of modeling your own vocabulary, what it was like to scope and create your terms, and what changes – if any – you needed to make after you tried to encode your own instance.

(2) What it was like to try to make an instance of your classmate’s vocabulary. Did any terms confuse you? Was anything particularly clear? What did looking at someone else’s terms and definitions teach you about modeling a vocabulary?

(3) What was it like to see the instance your classmate encoded of your vocabulary? Did it match the expectations you had for your vocabulary? And what does that tell you about the success of your scope, terms, and definitions?  

Part 6: Creating a DTD (optional)

If you want to develop some additional XML competence, create a DTD for your event model and encode it in a file called YourNameA3.dtd. I haven't given you enough instruction to do this, but you can get a very nice tutorial in the "XML Nutshell" book available at http://proquest.safaribooksonline.com/ if you are the UC Berkeley network or using the proxy server from off campus. Chapter 3 is about DTDs, and everything you need is in section 3.1 and 3.2. You should skip 3.1.3 (you will be creating your DTD as a separate file, not writing in "inline" in your instance) and section 3.1.4 (you'll be using your XML editor to validate). Ignore 3.2.9 (about "ANY" because that is a tool of the devil that makes for bad DTDs). And if you follow my advice about using only elements in your DTD, you won't need to learn anything about attributes and can write a simpler DTD.

Note: The “No Busy Work” Principle

Assignments are meant to challenge you intellectually in some way, not to see how much "busy work" you can put up with. So we’ll never intentionally ask you to do something that takes time but that doesn't give you more insights. Put another way, if you find yourself doing busy work in an assignment, re-read the instructions to see if they advise against doing what you're doing. If that doesn't end the busy work, ask Bob or one of the TAs if you're doing what is expected.

In this assignment there are ample opportunities to do "busy work," so be careful not to do it. For example, a "Syllabus Vocabulary" will probably have some notion of "Topic," and an instance of a syllabus might have many of them (the syllabus for our course has 29 of them). In step 3 of this assignment your task is to demonstrate how your vocabulary works by encoding an instance, but if you were encoding a syllabus instance it would be sufficient to encode just two or three topics, not 29. We're smart enough to realize that you knew what you were doing.