The Personal Self-Assessment Environment

Project 1 Software Requirements Specification

Last modified: Fri Aug 27 14:29:36 HST 1999

Overview

This semester, you will be incrementally constructing a "Personal Self-Assessment Environment"---a small software system that you can use to build assessment quizzes on topics of your choice. You can think of this system as a flexible, configurable set of "intelligent flash cards" that you can use to help you learn factually-oriented material. Each assessment quiz consists of a set of multiple choice questions, where one or more of the potential answers can be correct. No "short answer" or "essay" question types are allowed so that the system can automatically grade and correct your answer on each question. Some example application areas for the personal self-assessment environment are learning vocabulary words in a foreign language, important events in history, or technical concepts relevent to a certification exam. Note that many technical certification exams are multiple choice and automatically graded, making this software ideal for certification self-study.

The basic components of the Personal Self-Assessment Environment are:

A file format for storing questions and answers, which we'll call the "QA" format (for Question and Answer).
QA-Reader: A mechanism for reading a QA file into memory.
QA-Presenter: A mechanism for presenting the multiple choice questions in a file to the user and storing their responses.
QA-Grader: A feedback mechanism for checking the responses and providing the user with corrected answers.
QA-Editor: A mechanism for defining questions and answers and writing them out in the QA file format.

The initial set of projects will focus on creating simple versions of these components. Later in the semester, you will extend your initial components with enhancements to support more advanced and interesting features. Thus, it is to your advantage to design even the simple components with an eye toward future extension and enhancement. To help you with this process, here are some of the potential enhancements you may be making to the basic system during the semester:

Providing two kinds of questions: multiple choice, multiple answer (i.e. checkbox-based) and multiple choice, single answer (i.e. radio button-based).
Reading and writing multiple QA files.
Organizing sets of questions into quizzes.
Computed answers. Here you provide a formula, such as how to convert fahrenheit to centrigrade, and a range of acceptable fahrenheit values. The system then generates questions asking you to to convert a fahrenheit value within the range to its equivalent centrigrade value, and uses the formula to check your response.
Downloading QA files from the web.
Recording the elapsed time and comparing it to a recommended value.
Recording scores in a file. (Useful to assess progress).
Randomized presentation of all questions.
Randomized presentation of all answers to a question.
Randomized selection of a subset of questions. (i.e. any 5 of the 10 questions).
Support for embedded graphics such as gif or jpeg files in questions.
Support for embedded applets in questions.
Assistive technologies.
Palm Pilot version using the KVM for Java.
History-based question selection, based upon prior quiz results to focus on questions that were incorrectly answered previously.

Project 1 Increment: Simple QA file input

For this first increment, the project requirements are extremely simple. All you will be required to do is build a Java2 program that can read in a QA file, build an internal representation of the questions, and write out all the questions you've read in. The only complexity is that the file is not guaranteed to be a legal QA file. Thus, your code must behave reasonably (i.e. not crash) with both legal and illegal inputs.

Here are the specific requirements for this project.

The code must be formatted according to the 613 Java Coding Conventions.
You must write JavaDoc comments for each package, class, method, and variable, and generate the JavaDoc documentation html files for your system.
The program must process the command line switch "-qa", which should be followed by a file name. This tells the software that it should read in a file containing questions and answers. It must also process the command line switch '-list' which tells it that, having read in all the questions, it must print them out in the order they were read. Command line switches can appear in any order. An example invocation is:
```
% java -jar johnson-P1.jar -qa test.qa -list
```
This invocation loads your program from the file johnson-P1.jar, and passes it the command line args '-qa java-cert-ch-1.qa'. I will require you to use the Java2 jar file facility for packaging and submission of your programs this semester. For instructions on how to use the jar facility, see: http://java.sun.com/docs/books/tutorial/jar/basics/run.html. I've also created a simple set of instructions in jar-files.html.
The system must read in files formatted according to the PSAE File Format Specification.
By default, the system should print out the name of each question encountered once it is successfully parsed, or that an erroneous input was encountered. In general, the system should be able to recover from syntax errors in a single question and go on to parse the remaining questions successfully.

The system should begin by printing out the system name, version number, and the system author's name. After loading all of the questions, it should write a message to standard output indicating how many were successfully loaded.

Here is an example run of the system:

% java -jar johnson-P1.jar -qa test.qa 
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Package
Loading question title: Bar
Bad Question encountered. Continuing.
Loading question title: Foo
3 questions successfully loaded.

Note that in this invocation, the '-list' parameter was omitted, thus the questions were not written to standard out after loading. Here is an example run of the system with the -list command line arg:

% java -jar johnson-P1.jar -qa test.qa -list
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Package
Loading question title: Bar
Bad Question encountered. Continuing.
Loading question title: Foo
3 questions successfully loaded.
Listing of loaded questions:

Type: MC:N
Title: Package
Category: Bar
Question:
Example question 1.
Answer:100
Example answer 1
Answer:0
Example answer 2


Type: MC:N
Title: Bar
Category: Bar
Question:
Example question 2.
Answer:100
Another example answer
Answer:0
Yet another example answer.

Type: MC:N
Title: Foo
Category: Bar
Question:
What does foo mean?
Answer:100
Foo is the canonical meta-syntactic variable.
Answer:0
Foo is a transmogrification of fubar.

Thus, the requirements for this project increment focus entirely on command line processing and input of a .qa file. For this increment, you don't need to actually do anything with the questions once you have read them in, other than to write them out if the -list command has been specified.

Philip Johnson

Last modified: Wed Sep 1 13:08:40 HST 1999