Project Requirements

This draft document describes the high-level project requirements for the fall 2010 section of this course.

Gradebook NG (Next Generation)

As a part of the TUBBK (The Ultimate Blackboard Killer) initiative, Gradebook NG will manage all aspects of grading a collection of academic courses, in particular, storing grades and communicating them to their recipients.

General Requirements

Course Offerings

Courses can have multiple instances (sections), each of which is taught by one or more instructors.

Gradable Items

Every section has its own breakdown in terms of gradable items, optionally grouped by categories. This should be configurable on a per-course-instance basis.

Gradable items should be weighted, and this information could be used, for example, to automatically compute the final grade.

You should not assume that all of the categories are pre-defined. It is true that most courses have quizzes, homework, and projects. But every course is different in terms of its content.

(To keep the scope of this project manageable, the system will not include a mechanism for submitting work to be graded.)


An important question is how do people get into the system initially. At many institutions, the instructor is given a roster with all pertinent student info (student ID, contact phone number, etc.)

This information could be used to authenticate a user who wants to submit for the very first time. A student enrolls simply by providing his e-mail address and answering some information. (Last name, last few digits of ID, and perhaps one other piece of information.) An e-mail is sent that, if not acknowledged, will result in non-enrollment in the submission system.

Of course, ideally, the instructor may also enroll a student, but the whole goal in developing any such application should be self-maintenance. 

To keep the scope of this system manageable, enrollment is performed by an administrator.


Students should be able to see all of the graded items in real time once the items have been released. (Workflow for approval and notification can be added for extra credit, please see below.)

Instructors and teaching assistants (TAs) should be able to see grades in table format.

Instructors and TAs need the ability to enter grades easily using suitable forms. For some items, such as exams, a batch-entry mode is needed. For others, such as programs, single entry is needed, because the TA (usually) will write a detailed report and justification for the grade.

List manipulation

Whenever dealing with list-like structures that the user is allowed to modify, the following edit operations should be supported:
  • create
  • read
  • update (modify, including rename)
  • delete
In the interface, modification is invoked by selecting the list item to be modified. In some cases, the user is allowed to modify an item but not the list containing the item, while in other cases, the user is allowed only to view the detailed information on an item.

Authentication and Security Roles

The various user security levels and associated roles are as follows. There is no unauthenticated guest role in this system; all roles require authentication with a userid and a password.

The capabilities listed here refer to various entities whose detailed descriptions can be found below.


A student can
  • log in/out
  • modify the email address associated with his or her profile
  • view a list of class sections in which he/she is enrolled along with the current overall course grade for each section
  • choose a class section for which to view a detailed list of items with grades (where available) and the current overall course grade
  • view the grade for a specific gradable (may include an explanation and other information)


A TA or grader can
  • log in/out
  • view a list of class sections for which he or she is a grader
  • submit a grade (with an optional explanation) for a student on a specific gradable


An instructor can do everything a grader can do, plus
  • specify the list of gradables for a class section, including those that are submitted (homework, projects) and those that are not (quizzes, exams)
  • specify the maximum scores and relative weights for the gradables in a class section (the system should ensure that the weights add up to 1)
  • view a grade report for a specific gradable or for selected gradables, including statistics such as count, min, max, mean, median, bottom quarter, top quarter


An administrator can
  • add, modify, and remove users
  • add, modify, and remove class sections
  • enroll students in sections and drop students from sections
  • associate sections with one or more instructors and/or graders

Object Model

The high-level object model consists of the following classes and attributes:


A user has the following attributes
  • first and last name
  • password
  • email address (also serves as login ID)
  • roles


A class section (instance of a course) has the following attributes
  • instructor(s)
  • grader(s)
  • students
  • gradables


A gradable item has the following attributes
  • maximum score
  • weight
  • categories (zero or more)


A category is a symbol or tag with these attributes
  • name
  • description

Extra Credit Opportunities

Grading Workflow

When an item is graded by an instructor or teaching assistant, the grade does not necessarily get published to the student immediately. Therefore, it is essential to think about the workflow model somewhat.

Specifically, the system could be configurable how grades flow to students. If a TA gives a grade, some instructors want to see the grades before publishing them. Modelling such ideas is a well-known technique known as workflow.

In particular, the system could be set up to allow an instructor to approve a grade on a per-student basis or for an entire gradable (the student(s) affected are notified by email of the availability of their grade(s)).

Grade Disputes

A mechanism for students to dispute a grade. The system allows the student to enter an explanation of the dispute and notifies the instructor(s) by email.