CSCI 265 Phase 2: team repo, standards, requirements

CSCI 265 Phase 2: team repo setup, standards and procedures, project requirements

Phase 2 is focused on establishing the standards and procedures your team will follow, setting up the team's gitlab/github repo for the project, and producing detailed requirements for the product you are creating.

There are four core deliverables for phase 1:

writing and submitting a team standards and procedures document (due by 5pm Tuesday October 1st)
writing and submitting a detailed project requirements document (also due by 5pm Tuesday October 1st)
setting up the team's github/gitlab project repository (also to be completed by 5pm Tuesday October 1st)
giving a 15-minute team presentation on your project requirements and your standards and procedures, to be done in your team's lab section (October 2nd or 4th depending on your lab section)

Marks breakdown [30 marks total]

Repo setup [5 marks]
Standards and procedures [5 marks]
Requirements [15 marks]
Presentation [5 marks]

Sample versions of most project documents can be found here, based on a fictional team and project.

Setting up the team gitlab/github repo

The team needs to:

meet and agree upon whether they will use gitlab or github for their team repo,
have one person set up the team project repository on the chosen platform,
make sure everyone on the team has access to the repo and has logged in to verify that
grant the instructor access to be able to view the repo contents,
set up the repo internal structure so that it matches what the team has described in the version control section of their standards and procedures,
edit the repo readme to clearly describe the repo structure: in particular where the relevant project documentation can be found (I would strongly prefer that all documentation be kept together in a single clearly-named and easily-found directory)

Discussions on setting up gitlab/github repos can be found at URL
csci.viu.ca/~wesselsd/courses/csci265/labs/gitlab.html

When inviting the instructor to your repo:
- on gitlab.csci.viu.ca I'm @wesselsd David Wessels
- on github I'm DaveWesselsVIU
both use my David.Wessels at viu email address.

The standards and procedures document

This document is to be named standards.md and kept in your team's documentation directory, and is to follow the template shown in this skeleton version.

This document needs to clearly spell out:

the documentation standards and processes you'll be following, including
- any templates or guidelines you'll be following (a url/link is fine if you're following an existing industry standard),
- any rules/tools to be used in spelling and grammar checking,
- how you'll check/proofread each other's writing to ensure it follows the standards,
- how you'll coordinate putting the parts together if different people are writing different sections of a document (and ensure it can all be done in time for the submission deadlines)
the coding standards and processes you'll be following, including
- either your own written set of standards or links to existing industry standards,
- any rules/tools to be used in formatting/checking code,
- how you'll review each other's code to ensure standards are followed.
the version control standards and processes you'll be following, including
- the overall structure of your project repository, including decomposition into areas like development, staging/testing, and production/grading,
- roles and responsibilities for the maintenance/handling of the repo,
- rules regarding the processes to be followed when either pushing to the team repo or sending pull requests to have a designated person update the repo,
- rules around the handling of branches within the team repo,
- rules or templates for git commits, pull requests, readme files, etc,
- how you'll check/enforce that these standards and processes are followed.

The requirements document

This document is to be named requirements.md and kept in your team's documentation directory, and is to follow the template shown in this skeleton version, but the template has been deliberately kept vague since the actual content needed for the requirements document will vary tremendously from product to product. (E.g. what you need to describe for a game will be vastly different than what you need to describe for a new social media product, and both will be vastly different that what you need to describe for a project management tool, etc.)

The requirements document should give the reader a complete picture of every facet of the product from a user perspective: what it is for, how to use it, how every feature works, what every screen, menu, option, and element looks like, what the navigation structure is for moving from screen to screen, what to watch out for when using the product, etc etc.

It should also do so in a way that is easy to read and yet also serves as a strong reference tool - making it easy to find any specific bit of information you might be seeking. From the perspective of the developer, this should describe every detail about the product they are going to code so that they are not responsible for making behavioural/value choices as they design and code.

A common failing in a requirements document is a lack of specifics: suppose it states something like
"A character starts at their maximum health value and takes damage each time it is struck with a weapon (sword, dagger, or arrow)."
Somewhere (perhaps here, perhaps in a table elsewhere, but somewhere) the requirements need to specify exact values for every aspect: exactly what is the starting health? how much damage is inflicted by a sword blow? by a dagger blow? by an arrow? If there are modifiers that influence the damage then precisely what are they and precisely how is the modified damage calculated?
After producing a first draft of the requirements have everyone read through the document looking for places where it mentions a value or feature or calculation without precisely stating the range of permissible values, the default value, a precise formula for the calculation, the behaviour expected in case of errors, etc.

The document can often be based on the original proposal, but going into much much greater detail on every aspect (again, providing complete details for every screen, every menu option, every feature, every on-screen element, every calculation, every message displayed, every user input taken in, every error check and error message, etc etc).

This is going to be one of the largest and most important documents your team produces this term: it serves as the basis for your design and your test plan, ensuring everyone can tell exactly what every aspect of the product is supposed to be doing under every circumstance.
It is strongly recommended the entire team take on responsibility for different sections, start early, and meet/review/discuss the content multiple times as you develop the document.

The in-lab team presentations for phase 2

As with phase 1, each team will have 15 minutes to give a formal presentation discussing their current deliverables.

This presentation should

Begin with a short project update, describing any major changes in the nature/direction of the product or the structure or charter of the team.
The bulk of the presentation should focus on the product requirements.
A few minutes at the end should be spent discussing key points on the team's chosen standards and procedures, with greatest emphasis on the version control processes you have established.

Assessment and marks

Be sure all team members have read the contributions assessment page, and complete and submit their assessments within 48 hours of the scheduled phase 2 presentations (phase2.md in your individual contributions repos).