Software Engineering

Iteration 1: Requirements

Due on October 1st at 11:59 PM.

The master branches of your group’s repository and wiki will be pulled at that time and its contents will be graded. Be sure that all materials – documentation, code, build instructions, etc. – are available in that repository. If some materials cannot be placed in that repository, contact your instructor for instructions on how to compensate.

Please be sure to follow appropriate etiquette when interacting with your group.

Overview

The purpose of this iteration is to formalize the requirements of your application. You must know precisely what you’re trying to accomplish in order to complete your project (or judge whether you were successful). As a team, you will describe the domain of the problem you are solving, the manner in which you intend to solve it, and how the user is expect to interact with your software when it is complete.

There will be no code in your submission. This part of the software engineering process is about understanding the problem and formulating a solution; it isn’t about programming.

Formalizing Requirements

The formalization of your requirements should tell a story about something you intend to use software to improve. You might describe a problem and how you intend to solve it. You might describe a game and how you intend to make it playable. While the specific approach depends on your problem domain, the formalization of requirements will be the same for each project group. You will use the wiki associated with your project’s GitHub repository to present the following materials:

A vision statement for your project. This doesn’t have to be different from the statement in Iteration 0, but you may update it if you wish.
A feature list enumerating the distinct features of your application. This will expand on your vision statement and essentially give you a to-do list. Features should be separated into a list of core features (which are to be implemented earlier as definite functionality) and extended features (which are wishlist items and will be addressed if time permits).
A set of UI sketches indicating how the user interacts with the application. Every project has some form of user interface; your UI sketches should show how the user would navigate that interface to use the software for its intended purpose. These can be scans of hand-drawn diagrams, but they must be informative. Use concrete examples of data in your UI sketches; don’t just put ellipses everywhere that data might appear.
A domain analysis which describes the features of the application domain relevant to the project. There are a variety of UML diagram forms which could be used for this purpose. Often, a UML class diagram or a UML entity relationship diagram is a key component of a domain model. You may also include other diagrams, informal figures, or prose.
If necessary, you may wish to describe use-cases for your project. You may use UML use case diagrams and formal UML use-case syntax. Alternatively, you may produce storyboards (much like the UI sketches above) to illustrate how an actor would complete a task in your application. You should also describe the actors in the project. Do not include trivial cases (e.g. login) at the expense of more complex and domain-specific cases.
Give an architecture proposal. Describe the devices and components involved in your project and describe how they will interact, preferably with a UML deployment diagram. Identify the major software packages you will use in this project; this includes libraries, frameworks, build tools, and so forth.
If your project is similar to existing applications (e.g. a side-scrolling platform game), name a few such applications and identify what makes your project unique (e.g. “Unlike the Mario Brothers series and similar platform games, this project includes a realistic physics engine. This has a significant impact on the player’s experience, related game features, and level design.”).

The success of a group in this course can often be predicted by how complete the project’s requirements are! If your group is not in agreement about what the software should be, you might find out only after a lot of wasted time in design discussions or debugging sessions. It’s important to be thorough in this phase of your project, since the work you do here guides the rest of your project. Some examples of common mistakes are:

Failing to provide a domain model during domain analysis. Even if your documentation doesn’t include a complex domain, you should sketch out a class diagram of your domain to be sure. Remember: domain classes don’t include things like the UI or network interaction, but they do include any of the data you need to understand the problem you are solving. You may discover when you mock up the class diagram that your domain is more complex than you think!
Providing an incomplete or vague feature list. Your feature list is very nearly a to-do list for the remainder of the semester. You want to be fairly detailed about your features so you all agree what they will be and so you can follow them as your work proceeds. Consider ways to break down vague features. For instance “user can play the game” is far too vague and could be replaced by “user can move the character around the world”, “user can talk to other characters in the world”, etc.
Important use-cases are missing. Major features of your application should be explained in use-cases or storyboarding. If you are writing a calendar application, there should be a storyboard of a user adding an event to the calendar.

In general, the purpose of this documentation is to describe to the audience what your software will do and how it will do it. Although you will work on this same project throughout the semester, it should be possible for you to hand your requirements documentation over to another group and allow them to complete the rest of your project without having any major questions.

Example

A fairly complete example of this documentation from a previous section of this course at a different institution can be found here.

Deliverables

You must store all of the above documents in your group’s repository wiki. You must have a single page called Requirements representing the requirements document (like a table of contents), but you are encouraged to separate each of the requirements above into distinct wiki pages both for organization and to avoid merge conflicts. If you have any documentation which cannot be stored in your wiki, contact your instructor to discuss the situation.
You must create/update a README.md file in your repository’s root which refers to the project wiki for documentation. This will ensure that newcomers to your GitHub repository can find the information they need.

Iteration Review

You are also required to submit an iteration review which assesses the work you and your peers completed and whether things are going well for you in class. This review is private; its content will not be shared without your consent. Click here to submit your Iteration 1 review.

It is in your interest to provide honest feedback, even if that feedback isn’t the most generous or positive; if there’s a problem, your instructor needs to know!