Skip to Content

Github Wiki Requirements

Posted on 7 mins read

My CS 371 and CS 581 team projects must use the GitHub Wiki for project documentation. Below are pages that must be included; you are free to have other pages. You must use at least simple Markdown syntax to format your pages.

Home Page

Your home page must “introduce” your project and your team – think about someone who is not familiar with your project starting here. This page must contain links to all other pages.

Problem Statement (project overview)

This page must contain your problem statement (the overview of what your system will do for users), the End User Profile, the Value Proposition, and the Product Core. Those final three items are taken from Bill Aulet’s Disciplined Entrepreneurship.

While the initial project ideas were very short descriptions of rough ideas, the project problem statement is more in-depth, fleshing out the major details and trying to capture the actual scope of the project without attempting to write a full-blown every-detail requirements document. The project problem statement should be perhaps 1-2 pages if it was printed. If your system is a game, your problem statement should contain a relatively detailed description of the gameplay, including rules. You can, if you want, put game rules in a separate wiki page, and link to it from here.

The End User Profile describes what your primary end user “looks like”. What are their capabilities? What are there deficiencies? Why? You need to keep focused on your end user so that you build a product that actually meets their need.

The Quantified Value Proposition briefly describes the value your product will create for the customer. The Product Core describes the single thing that your product will do better than any others. This will help your project effort to focus on what really matters. It can be worthwhile to add a description of the Minimum Viable Product as well, which is the minimal product that is actually useful to customers (this is V1.0 of your product).

User Stories

You must have a page that lists your user stories. You will capture the functional requirements of your system in user stories, a popular agile method for documenting and writing down system functionality. Each user story must have a number, a title and then have its main story statement in the form of:

As a role I/we want to capability so that goal.

The role is the particular type of user role that will use the described capability; the goal is why the user needs or wants this capability in your product. The user story also must have an elaboration (a short descriptive paragraph), and it must have an effort estimation using dimensionless Fibonacci numbers. For a starting scale, consider your entire project to have an estimate of perhaps 144 or 233 (both Fibonacci numbers). It also must have an acceptance test description, which should be a short description of how you will validate that this story was successfully implemented.

NOTE: these are user stories, not developer stories! You (as a developer) are not a user!

An example (for some business team management app):

3: Export to CSV

As a manager, I want to export my team’s timesheet data to a CSV file so that I can use it in a spreadsheet or write a script to do my own processing.

Effort Estimation: 8

Elaboration: Users should have the ability to use their data for purposes outside our system, and so we need to support a data export capability; since the CSV (comma-separated-values) file format is fairly common, we will use it as our export format. This will apply only to data that can sensibly be represented in CSV (perhaps we should support JSON for other?).

Acceptance Test: Perform export operation in user interface on demo data and import the resulting CSV file into OpenOffice Calc and Microsoft Excel. Show that both apps import the CSV properly. Perform export on a full set of demo data, on data containing 1 element, and on an empty data set.

======== end example user story ========

Domain Model

This page must display a domain model as a UML class diagram, and then have some explanatory text about the problem domain for your system. See the link above for more info. This is not a class diagram of your program.

Sprints Page

Sprints must be documented on this page, and this page must be updated at the end (beginning) of each (next) sprint. Each sprint must have the following documentation:

Sprint dates: the begin and end dates of the sprint.

Sprint goals: the planned work accomplishment for this sprint; include a description of what will be demonstrated in the working software increment.

Sprint scrum master: identify which team member is the scrum master for this sprint.

Sprint velocity: After the sprint is over, add up and report the total number of story points that were completed; the points must come from the completed issues.

Team performance: After the sprint is over, describe what each team member contributed, and give a rough estimate of the percentage of contribution they made; all team members' percentages must add up to 100.

Sprint reflection: After the sprint is over, describe what went well in the sprint, and what did not go well. Also describe any changes to work habits and management that you will make for the next sprint.

Nonfunctional Requirements

The User Story page should be capturing the functionality of the system; this page must describe the nonfunctional requirements of your product. At minimum you must address these categories:

  1. Hardware and external software requirements: what kind of hardware, operating system, and other software does your product require to run? Be realistic, if your product does not need a high-performance gaming PC, do not say that it does.

  2. Security: describe what level of security your product needs and describe particular information it might have that is sensitive; describe what kind of potential access points exist in your product that someone might use to hack it (e.g., does it receive network communication?).

  3. Performance: describe reasonable user expectations of performance for your product.

  4. Usability: describe the levels of usability of your system, and relate these to your end user profile. Are there basic and advanced modes or capabilities that need well-separated in your user interface?

  5. Reliability: describe where and to what level your system needs to be reliable.

Software Design

This page will contain a description of your software design.

It must include a UML class diagram of your system design (uploaded as an image file and then embedded in the page). This is very different from a domain model, and should be the actual classes in your code (and intended ones not yet implemented) and their relationships (inheritance, aggregation/composition, and association). Any place in your code where an object of one class holds a reference to an object of another class (and probably uses it), you should have some connection between the classes in your UML diagram.

It is not enough to just have a diagram; the diagram must be explained. So, this page must also include a description of the class-level design of your system: what are the major classes and what are their objects' responsibilities, are they singleton classes, etc. Your document should also discuss control issues, e.g.: Are you using threading? Is there external communication that affects control? Think of it this way: if you were just hiring on to the project starting at this iteration, what would YOU want to be able to read about the system so that you can understand it and start contributing? The good design document will be exactly that (and will get graded highly!).

Verification and Validation

Your wiki must have this page to explain how you performed verification and validation activities. Mostly this will involve explaining your testing activities. Recall that verification is the idea of internal function working as intended (“Did we build the product right?"), while validation is the idea of whether the product actually meets the customer’s needs (“Did we build the right product?").

It would be great to refer to using JUnit on some parts of your product; if you do, explain what parts, and be sure your JUnit tests are part of your project repository (not the wiki repository). You can embed screenshots in this page if you want, of JUnit tests running.

It would also be great to show some JaCoCo code coverage analysis results; this is actually easier than JUnit because you don’t need to actually create any tests. If you do this, you can commit your final JaCoCo html report into your project repository, and you can embed screenshots into this page.