GP1: Requirements

Due: Monday, Sep 21st

Image source: freepik.com

Your team owns one feature area of plan.cs.jmu.edu. The System Description says what that area is responsible for and where its edges are. It does not say what your tables must do, and that is what this assignment is for.

By the end of GP1 you should be able to hand your document to another team and have them understand what you are building well enough to argue with you about it.

What to write

Your deliverable is the README.md in your team's directory. Aim for 1200 to 1500 words, which is about three printed pages. Write in plain prose and complete sentences, except where a list is clearer. Do not repeat the System Description; assume the reader has already read it.

Here is an example README.md for a project we are not building. This file shows the format and the level of detail expected.

Overview

An opening paragraph describing your area in your own words. Not what the System Description says it is, but what you now understand it to be after talking it through.

Use cases

Six to ten statements in a bullet list. Each one names an actor, says what that person is trying to accomplish, and says what the system does in response.

A use case is specific. "An advisor reviews a plan" is not a use case; it is a category. "An advisor opens the plan of an advisee who has not registered yet, sees that two of the three remaining major requirements are unmet, and leaves a recommendation to move one course a term earlier" is a use case, because you can tell whether a database supports it.

Cover the ordinary paths and at least two that are awkward: something that fails, something a person does wrong, or something the department only does once a year.

Proposed queries

Eight to twelve queries, written as questions. These are the questions your data must answer.

Mix two kinds. Some are lookups that one screen of the application needs, such as retrieving one record and the things attached to it. Others are analytical, spanning many rows and answering something a director or an advisor would actually ask.

Be concrete about what a good answer looks like. "How many students are affected?" is too loose. "How many students bound to the 2024 catalog still have an unmet writing-intensive requirement?" can be answered or not answered.

These will come back

In GP4 you will write analytical queries, and this list will be your starting point. A team that writes vague questions now spends November inventing them under time pressure.

Proposed tables

Name and describe 8–10 tables. For each one, give a name and a single sentence saying what one row represents. Table names should be singular nouns and lowercase.

Do not specify columns, keys, or types. That is GP2, and committing to them now will only mean unpicking them later. Say "one row is one attempt by one student at one course" rather than listing six column names.

If you are unsure whether something is one table or two, say so here and give both readings.

Boundaries

A few short paragraphs describing what crosses the boundary between your area and the others. Say what you will need to read from another team's tables, and which team owns it. Say what you expect other teams will need from you.

Remember that your tables may reference the core schema and may never reference another team's tables. If you find yourself needing a foreign key into another area, that is a design problem worth naming now rather than discovering in October.

Assumptions

The System Description does not settle everything, and some of what it does settle you may want to push back on.

• List the assumptions you are making where the domain is ambiguous.
• List the "open questions" you could not answer and would need me, an advisor, or a program director to resolve.

This section is graded on how good the open questions are, not on how few of them there are. A team that finds three real ambiguities has done better work than a team that found none.

Out of scope

Three to six things a reader might reasonably expect your area to cover, and that you are deliberately not building. Say briefly why for each.

Team members

One paragraph about each team member. Focus on academic and professional experience, not where you were born and what your hobbies are. For example, you might list the most recent CS courses you have taken, software projects you have worked on in the past, and background abilities and skills that you will bring to the project.

Note

The paragraphs in this section should be about the same length for each team member. Don't allow a team member to write significantly more or less about themselves.

Grading criteria

Specificity above everything. A document full of true but unfalsifiable statements earns less than one that commits to particulars and gets some of them wrong.

I am also looking for evidence that four people worked on it, that you understood the boundaries of your area, that your proposed tables plausibly cover your use cases, and that your questions are the kind that will still be interesting in November.

Submission and review

The class repository opens on Thursday, Sep 17, and your team's branch will be waiting for you. Draft wherever you like before then. From Thursday on, commit to the branch as you write rather than all at once on Monday night. For GP1 only, I am reading the commit history from Thursday forward, since the repository did not exist before that.

Open a pull request by the deadline. See the GitHub Workflow for how branches, pull requests, and reviews work.

Your reviewing team has 48 hours. Reviewers, focus on three things: whether the use cases are specific enough to check, whether the proposed tables could actually answer the questions listed, and whether anything in the document belongs to your area instead of theirs. Say what you would ask for if you had to build from this document.