CompSci 408
Fall 2020
Delivering Software:
From Concept to Client
A semester long project can easily get off track without consistent effort made each week and regular evidence of your team's progress. In this course, we will be using Scrum to help manage the project, with Sprints lasting two weeks, to emphasize agile project principles that will help manage your client's expectations, respond to changes and setbacks, and deliver as much direct value as possible.

Scrum, and good modern programming practices in general, try to create a rhythm to the work and, in this course, the rhythm will typically be:

This does not mean you should do no coding during the first week, just that we will be asking for some evidence of your planning and thoughts during the first week.

Project Deliverables

The following deliverables are expected during the semester:

Regular Meetings

Outside of class, we expect you to meet as a team at least once each week and to meet with your client minimally every two weeks. Note, scheduling meetings is difficult with so many people that have different kinds of schedules so plan well in advance when trying to schedule time with your clients or your mentors. The entire team is expected to attend the initial introductory meeting with the client. In general it is strongly encouraged that everyone strive to attend all client meetings, but at least two students must be present for any meeting with a client. For all meetings (with your team, client, or course staff) your team must use this template included in your repository to submit:

See these notes on effective meetings. Just like this meme, Open Source software has a saying "Keep a history: if it isn't public, it didn't happen".

Client Sprint Demos

During the week after each Sprint ends, you must meet with your client to show them a working version of the project's progress (i.e., not just test code or working dev tools). It is important to let the customer "drive" the app so you can watch them interact with it; doing the driving yourself while the customer watches is not effective. These meetings are the time to align expectations between you and your client, discuss your progress, get feedback on how well the features implemented match the client's vision, and prioritize the work to be done in the next Sprint.

Note, this demo with the client is separate from the in class demo required for each Sprint.

File Formats

People use a wide array of different devices (Windows, Mac, tablet, or smart phones) to access their information, so you should not send platform specific documents out to team members or course staff. Submit only code, text (.md, .txt, .csv, or .xml), HTML (.htm, .html, or .css), PDF, image (.gif, .jpg, or .png), video (.mp4, .mov, or .avi), or sound (.au, .mp3, or .wav) files. You are free to use any programming environment available to complete your work, however, you are responsible for converting it into one of the standard formats listed above (most current programs can save or print files to a variety of alternate formats).

All deliverables must be pushed to your Gitlab repository by the due date given unless you have made separate arrangements with your instructors and client.


Sprint 0 - Discovery

The goal of this initial Sprint is to understand the problem you will be tasked with solving during the semester by meeting your team and your client, learning the project's details, determining what technology makes sense to use, and choosing how your team wants to work together. This is the only Sprint with no public demo.

Team Contract

This document serves as an agreement between all team mates about how the team will operate — a set of conventions that you plan to abide by. It should be created collaboratively by thinking about good or bad aspects of team project experiences you have already had, your goals for the course, how the team should communicate, and the quality of work everyone wishes to achieve, and the level of group participation and individual accountability everyone feels comfortable with. The process of generating a team contract usually helps jumpstart a group's efforts to become a team by immediately focusing everyone on a definite task that requires communication and negotiation.

By adding this document to your project's repository, each team member implicitly agrees to abide by it.

Executive Summary

This document serves as a short summary of the project that anyone can read to understand what you are creating and why by giving a quick overview of the project for anyone interested (from people thinking about buying it on an app store to someone thinking about funding the project).

In about 1-2 "pages", complete the following sections in your project repository's Wiki using Markdown format:

Include a "catchy" name for your project as part of the title of the document. We recommend a short, descriptive, phrase. The client may already have a name picked out or it may take a brainstorming session with the team, client, and some users to find a good name.

Sprint 1 - Pretotype

The goal of this first Sprint is to sketch out a possible app by understanding your users, determining the scope of the features you estimate can be completed during the semester, choosing the roles you want to take on in your team, and forecasting possible outcomes for your team and your project. A Pretotype, or more specifically a working Wireframe, serves to sketch out a possible app by creating a mockup of its interface and navigation that emphasizes "failing fast", doing a simple, quick, demoable implementation to see if you are on the right track.

Project Contract

This document serves as the contract of the project's scope that anyone familiar with the project can read to understand what features you believe you can complete during the semester and why. It helps ensure all parties understand what will be attempted this semester.

In your project repository's Wiki using Markdown format, describe the goals, priorities, and concerns, as well as the team roles within the project:

User Interview Report

This document serves as a summary of your meeting(s) with potential users of this app that captures your understanding of their needs and goals with regards to the problem your app is trying to solve.

In your project repository's Wiki using Markdown format, describe what you learned from talking to potential users, as well as the impact of the project:

Demo Presentation

While having a "running", Wireframe, version of your app is encouraged (and fairly easy with modern drag and drop layout tools for web, mobile, or desktop apps such as this one or Adobe XD which is freely available for Duke students) it is not required — a hand or "PowerPoint" drawn series of "pages" that shows how the app's UI will look and flow is fine.  Note, implicitly, these pages serve as a "contract" with your client of what you intend to implement (or not) this semester, so make sure your client understands this.

Synchronously during class, your team will have 10 minutes to present a demo as well as some key ideas and highlights from this Sprint:

Note, you are expected to practice delivering the presentation beforehand since it is not a lot of time to fit in everything asked of you. For all parts, focus on the value your app represents to the users, not on the technical details about how it will get done. Everyone on the team should talk at some point during the presentation.

All materials used for your presentation must be pushed to your Gitlab repository or Wiki.

Wireframe User Testing

Letting potential users interact directly with your app early and often, while changes can still be made, is a vital part of the agile process and should be welcome. Make your Wireframe available to 2-3 users to work with in as realistic a way as possible (e.g., on a device or web site where they can click, or physically cut out paper copies of the screens to the correct size that they can flip through). Either record the interaction synchronously or ask each user to summarize their feedback individually after doing the test interactively with you or on their own if you cannot be present. Make sure each user understands the app's purpose, either because you interviewed them earlier or by giving them access to your Executive Summary.

As part of this process, if your app needs to collect data about users, make sure your testers understand:

Because user data is regularly stolen, sold, or used inappropriately, it is becoming an important issue for both companies, customers, and law makers. Mozilla and other companies have started championing Lean Data practices to minimize what data is needed to run their apps. At the very least, you need to justify your user data needs and practices (which will likely require a team discussion with your client).

In your repository Wiki, describe what the results of testing your wireframe with potential users.

Sprint 2 - Prototype

The goal of this Sprint is to implement minimal versions of the features most highly prioritized by the client to get a quick sense of how it will work, perhaps what makes the app unique or what is perceived to be most challenging or most uncertain. This Sprint emphasizes rapid prototyping on small example, perhaps hardcoded, data to get something working completely from the backend to frontend. Use this Sprint to also get your first feedback from your users and to clarify what data you need and how you intend to use and protect it.

Project Plan

This document serves to clarify the order in which the project's features will be completed that anyone familiar with the project can read to understand what how the features will be prioritized and who will be taking the lead on each feature. In this comprehensive list, called the Backlog, features should be described as User Stories, that refer to user personas, each of which will be broken down into a set of one or more tasks (Gitlab issues) that you feel confident can get down during a single Sprint. It helps ensure the team understands the client's priorities and demonstrates that the work can reasonably get done.

In your repository Wiki, describe the features you intend to complete as part of this project and during which Sprint you expect them to get done.

After reviewing and discussing the features for this Sprint, break down each one into a set of one or more tasks that can be estimated and entered into task tracking software that can be assigned to specific team members and easily updated to track the team's progress. Note, tasks may also be non-programming oriented, but it should be clear from looking at the distribution of tasks that everyone on the team is accepting responsibility for their fair share of tasks overall.

In general, we recommend you follow these steps when managing each Sprint.

Wireframe User Test Report

This document serves as a summary of showing your wireframe to potential users that captures your understanding of their feedback on what works and what could be improved. Letting potential users interact directly with your app early and often, while some changes can still be made, is a vital part of the agile process. User feedback can be ambiguous or even contradictory, so it is not this document's purpose to decide how to respond to the feedback — that will likely require a team discussion or a decision by your client.

Meet with 2-3 users and let them interact with your wireframe in as realistic a way as possible virtually rather than simply sending them a demo video. Try to record the meeting or ask each user to summarize their feedback individually after doing the test with you or the client if you cannot be present. Make sure each user understands the app's purpose (either because you interviewed them earlier or by giving them access to your Executive Summary) and the app's data needs:

In your repository Wiki, describe what the results of testing your wireframe with potential users.

Demo Presentation

Since this presentation serves to wrap up a Sprint, in addition to showing your team's progress on the app, it should show that your team has reflected on its progress and planned for the next Sprint. Your presentation should be limited to 10 minutes and can be done synchronously using Zoom or recorded and combined into a single shared video.

Record your team presenting a demo as well as some key ideas from this Sprint:

Note, you are expected to practice delivering the presentation beforehand since it is not a lot of time to fit in everything asked of you. For the functionality demo, focus on the value your features represents to the users, not on the technical details. Each person on the team should talk at some point during the presentation.

All materials related to your presentation must be pushed to your Gitlab repository or Wiki either as code, images, or written text (using Markdown). PowerPoint slides are discouraged because they are completely separate from the project and unlikely to be maintained even if they are added to the repository, but here are some tools to convert Markdown to a slide style format.

 

Sprint 3 - Baseline Prototype

The goal of this Sprint is to implement a more robust version of the core functionality, perhaps using some real data, and perhaps some minimal quality versions of the next set of features. This sprint emphasizes giving the client some confidence that the basic app is up and working and help give them a sense of what the final version can be. By the end of this Sprint, a version of the app must be deployed in some meaningful way (i.e., on your personal device or on a server others can get access to).

Test Plan

This document describes how the team intends to verify the project's quality such that anyone familiar with the project can read to understand how features will be tested, with both expected and unexpected input/interactions. This document serves the purpose of ensuring the team is committed to providing a high quality working project.

In your repository Wiki, describe the how you plan to use to test this project.

Test Scenarios

A scenario describes one or more steps necessary to test how each feature is used within your app by thinking about possible users actions and objectives for different possibilities, including those resulting in naive errors and those due to abuse based on users with hacker's mindset. A feature may have as little as two test scenarios (one positive and one negative) to a tens of scenarios depending on its complexity. There are many types of test scenarios at many different levels of the application, some of which can be easily automated but some of which may not be. For automating testing, we suggest using Cucumber scenarios for each feature.

The following should be included in each test scenario:

As many of these tests that can be automated should be converted to code that will be regularly run against the current version of your app using Gitlab's Continuous Integration Pipeline and an appropriate tool for showing your tests' Code Coverage (strive to achieve at least 80% lines covered by tests).

Release Management Plan

This document describes how the team intends to manage the project's software release such that anyone familiar with the project can read to understand how the stable release will be distinguished from the current development version as well as how the project's deployment dependencies (technology, libraries, resources, etc.) are managed. This document serves the purpose of clarifying the packaging and delivery of the elements of a product.

In your repository Wiki, describe your plan for the following:

Note, you can use Gitlab to simulate many typical DevOps features using its CI Pipelines to set up containers much like Docker, to run different commands based on different goals, and only accept Merge Requests on successful completion. Additionally, specific branches can be protected so they can only be accessed using Merge Requests.

Demo Presentation

Since this presentation serves to wrap up a Sprint, in addition to showing your team's progress on the app, it should show that your team has reflected on its progress and planned for the next Sprint. Your presentation should be limited to 10 minutes and can be done synchronously using Zoom or recorded and combined into a single shared video.

Freeze your master branch code, i.e., stop adding new features, at least 12 hours before you record the demo to allow time to practice your presentation and prevent last minute emergences. Fixing small bugs (and tracking those bugs) you find as you practice using your app for the demo can still be helpful but, in some cases, it may be better to find a workaround that can be practiced and used during the demo instead (e.g., using specific inputs, order in which features are presented, etc.).

Record your team presenting a demo as well as some key ideas from this Sprint:

Note, you are expected to practice delivering the presentation beforehand since it is not a lot of time to fit in everything asked of you. For the functionality demo, focus on the value your features represents to the users, not on the technical details. Each person on the team should talk at some point during the presentation.

All materials used for your presentation must be pushed to your Gitlab repository or Wiki either as code, images, or written text (using Markdown). PowerPoint slides are discouraged because they are completely separate from the project and unlikely to be maintained even if they are added to the repository, but here are some tools to convert Markdown to a slide style format.

Sprint 4 - Alpha

The goal of this Sprint is to implement a "demoable quality" version of as many features of the project as possible. This sprint emphasizes releasing an "alpha", i.e., buggy but complete, version of the project. At this point, to foresee possible problems in the future, this version must be deployed where the Client can access it on their own (i.e., on their own device or a public web server that is distinct from your development server).

Team Contract

This document serves as an agreement between all team mates about how your team will operate — a set of conventions that you plan to abide by. Revisit your original Team Contract in the project's Wiki based on the discussion in class using a Team Canvas and Social Contract as well as the reading Teamwork is an Individual Skill by Christopher Avery to assess what parts of the contract are still useful and what parts need to be updated or what needs to be added. Essentially, this gives your team a chance, now that you know each other better and have shared experiences, to create a more realistic set of goals that better reflects how your team wants to communicate and solve problems collectively, especially ways to handle negative team situations.

In your repository Wiki, update your Team Contract to reflect your team's collective goals for working together. By adding this document to your project's repository, each team member implicitly agrees to abide by it.

Design Justification

This document describes why the team has designed the software the way you have such that anyone familiar with the project and with a technical background can read to understand the project's organization, what choices the team made, what the design assumes will not be changed, and what the design attempts to make flexible so that it can be easily changed or extended. This document serves as a roadmap to help those that might maintain the software or make decisions about how the app will be extended in the future. This reading argues for the importance of this document, this reading describes a process for making decisions, and these are real-world examples.

In your repository Wiki, describe the high-level architecture and goals of your design (rather than low-level code specific implementation decisions). Like User Stories, you can also use stories to justify or explain design choices because they help make even abstract things like software design more comprehensible to non-technical members of the team. Additionally, justify significant decisions your team has made in relation to the project's design goals (whether it was code you wrote or a library or framework you used instead of writing it yourself) using the following template:

User Testing

User testing provides potential actual users with a chance to work directly with your app while some changes can still be made. Thus, focus on parts of the app that are close to finished or that you specifically want tested, i.e., that you want feedback on or are uncertain about. When conducting a User Test, provide potential users with the following information:

Create an online survey form for your users to take (i.e., Google docs, Survey Monkey, Qualtrics, etc). Depending on the type of survey, you can either create a separate website for the introductory materials or include it as an opening page where they click through to complete the survey. Your site/survey must include the following parts:

Encourage your client to participate in the user testing!

User Testing Report

In your repository Wiki, report the results of your user testing with potential users (make sure to clearly distinguish feedback from fellow students in class from that of expected users).

Demo Presentation

Since this presentation serves to wrap up a Sprint, in addition to showing your team's progress on the app, it should show that your team has reflected on its progress and planned for the next Sprint. Your presentation should be limited to 10 minutes and can be done synchronously using Zoom or recorded and combined into a single shared video.

Freeze your master branch code, i.e., stop adding new features, at least 12 hours before you record the demo to allow time to practice your presentation and prevent last minute emergences. Fixing small bugs (and tracking those bugs) you find as you practice using your app for the demo can still be helpful but, in some cases, it may be better to find a workaround that can be practiced and used during the demo instead (e.g., using specific inputs, order in which features are presented, etc.).

Record your team presenting a demo as well as some key ideas from this Sprint:

Note, you are expected to practice delivering the presentation beforehand since it is not a lot of time to fit in everything asked of you. For the functionality demo, focus on the value your features represents to the users, not on the technical details. Each person on the team should talk at some point during the presentation.

All materials used for your presentation must be pushed to your Gitlab repository or Wiki either as code, images, or written text (using Markdown). PowerPoint slides are discouraged because they are completely separate from the project and unlikely to be maintained even if they are added to the repository, but here are some tools to convert Markdown to a slide style format.

 

Sprint 5 - Beta

The goal of this Sprint is to create a robust, complete, version of all the project's functionality. After this sprint, no new features should be added — just bug fixes and changes made in response to user feedback. At this point, the app must be deployed in the Client's environment to prepare for the final hand-off.

User Testing

This is your final chance to get feedback from users so it partly an attempt to get feedback and partly an attempt to determine how successful your effort this semester was. When creating this User Test, provide potential users with the following information that is updated from your previous version but that does not assume they took your previous test:

Create a new online survey form for your users to take (i.e., Google docs, Survey Monkey, Qualtrics, etc). Depending on the type of survey, you can either create a separate website for the introductory materials or include it as an opening page where they click through to complete the survey. Your site/survey must include the following parts:

We will do a dry run of your tasks during class but also give your survey to a friend, and us, for feedback before giving it to the client.

Demo Presentation

Since this presentation serves to wrap up a Sprint, in addition to showing your team's progress on the app, it should show that your team has reflected on its progress and planned for the next Sprint.

Your recorded presentation should be limited to 10 minutes and include a demo as well as some key ideas from this Sprint:

Note, you are expected to practice delivering the presentation beforehand since it is not a lot of time to fit in everything asked of you. For the functionality demo, focus on the value your features represents to the users, not on the technical details. Each person on the team should talk at some point during the presentation.

Note, you are expected to freeze your master branch code, i.e., stop adding new features, at least 12 hours before you record the demo to allow time to practice your presentation and prevent last minute emergences. Fixing small bugs (and tracking those bugs) you find as you practice using your app for the demo can still be helpful but, in some cases, it may be better to find a workaround that can be practiced and used during the demo instead (e.g., using specific inputs, order in which features are presented, etc.).

All materials used for your presentation must be pushed to your Gitlab repository or Wiki either as code, images, or written text (using Markdown). PowerPoint slides are discouraged because they are completely separate from the project and unlikely to be maintained even if they are added to the repository, but here are some tools to convert Markdown to a slide style format.

 

Sprint 6 - Production

The final version of the app should have robust and full functionality, including any updates in response to User Testing, and the final documentation to help the Client manage the software after you leave the project.

Final Team Contract

This document serves as an agreement between all team mates about how your team will operate, a set of conventions that you plan to abide by, now that your team is more comfortable working together. This final version should be something the team would feel good about using to guide it if the project were to continue on next semester (so that it captures both what has worked to make the team successful and ways to help those things that are still not working).

Revisit your updated Team Contract in the project's Wiki based on the readings and class discussions relating to ethics to develop a code of conduct and values your team wants to uphold. Meet as a team to share your individual experiences and views on ethical topics from this semester to determine where your values align and differ — remember, ethical issues especially do not have right or wrong answers so make sure to practice empathy, understanding, and trust in trying to understand and value everyone's opinion. While you are not expected to agree on everything, as a team you should be able to create a reasonable compromise that everyone can accept.

In your repository Wiki, update your Team Contract to reflect your team's collective ideals for dealing with thorny issues that occur. By adding this document to your project's repository, each team member implicitly agrees to abide by it.

License Justification

This document describes how this project's code can be used going forward after you leave the project, such as: how your names will be associated with it, how much it can be modified, what kinds of other code it can be used with, and what kinds of things it can be used for. This document serves the purpose of clarifying these issues because experienced developers will not touch unlicensed code because, technically, they have no legal right to use it. This can be a complicated choice, with a variety of competing goals, because there are significant differences between licenses.

In your repository Wiki, justify your choice of license for your app (Open Source, Proprietary, or otherwise) as follows:

User Testing Report

In your repository Wiki, report the results of your user testing with potential users (make sure to clearly distinguish feedback from fellow students in class from that of expected users).

Demo Presentation

Since this presentation serves to wrap up the project, it should show what your team, and each individual, has learned during the semester.

Synchronously, during class, your team will have 12 minutes to present a demo as well as team and individual reflections from the semester:

Expectations:

All materials used for your presentation must be pushed to your Gitlab repository or Wiki either as code, images, or written text (using Markdown). PowerPoint slides are discouraged because they are completely separate from the project and unlikely to be maintained even if they are added to the repository, but here are some tools to convert Markdown to a slide style format.

Technical Documentation

This documentation contains all the information the client needs to use, maintain, and upgrade the app after your team has disbanded — it should reflect the current state of the project, not an idealized or bug free version. It is fine to copy, and update, from versions of documentation created earlier in the semester if it is relevant.

  1. Within your app, include an about page that includes your names, clients' names, Duke University, and any other supporters your client has had in their research (ask if you are uncertain)
  2. Within Gitlab, at the top level of your repository, include the following basic files:
    • Icon.png. image for your project logo (whether or not it is a mobile app)
    • README.txt. file that explains your project's purpose, its dependencies, and an overview of how to deploy your project
    • RELEASE_NOTES.txt. file that lists your project's current functionality, including any known bugs, assumptions, or limitations, and what platforms it has been tested on (including version of OS)
    • BACKLOG.txt. file that lists future features you would like to implement (it is a bad sign if this file is empty!)
    • LICENSE.txt. file that includes the license text your team chose for the project
  3. Within Gitlab, in a separate folder called doc, include three kinds of documentation for different audiences (these may be multiple files in different formats):
    • User Documentation. for non-technical users of the app in the form of HowTo Videos, Help Files, FAQs, notes about assumptions or expectations, etc.
      Note, if this is built into the app instead, that can just be noted in the doc folder.
    • App Maintenance Documentation. for technical IT managers responsible for the installing and maintaining the running app in the form of:
      • install instructions, especially requirements or assumptions about the target environment
      • list all open source tools or libraries your project uses, their versions, and links to their associated licenses
        Note, if this is included in a standard file as part of your project's build process (like pom.xml or package.json), that can just be noted in the doc folder.
      • data changes, address ways to update or change key non-programming components of the app, such as database information, data files, resource links, phone numbers, server addresses, etc.
        Note, do not forget to include necessary account and password information!
    • Technical Documentation. for programmers that need to modify the app in the form of comprehensive project code design documents, including:
      • in-code comments (especially your names within every file!)
      • database schema (you can generate a diagram from your database)
        Note, if a single, complete, view of this is built into the app instead, that can just be noted in the doc folder
      • overall architecture design (you can generate a diagram from your code or this one), including things like what you intended to be flexible, how you intended new features to be added, or why you separated the client/server logic the way you did
        Note, do not forget to include justifications for your primary design decisions!

Finally, your project must include precisely how to rebuild your app's server (if you have one) directly rather than relying on written instructions. You can do this using these options (in order of preference):