Princeton University
|
Computer Science 333
|
Spring 2024 |
The COS 333 project is an opportunity to undertake a larger and more elaborate task than any of the assignments: to design and implement a significant piece of software, working in teams of 3 to 5.
The intent is that this will not be just hacking, but a serious attempt to simulate some aspects of reality: choosing something suitable to work on, planning how to get it together, designing it before building it (though allowing for the inevitable changes of direction as things evolve), building it in stages, testing it thoroughly, trying it out on real users, and documenting and presenting the result, all as part of a small team. If you do it well, this should be something that you can show with pride to friends and prospective employers.
The project will involve many of the issues of software engineering as they occur in small, multi-person real-world projects. Some of this material will be discussed in class.
The considerations affecting the form of the project are:
A large number of real-world systems are based on what is often called the three-tier model: a user interface, a database for persistent storage, and some process(ing) between them. Many web services use this architecture. For example Amazon has a web-based user interface; the data are a catalog and customer information, and the process is a wide variety of searching and data-mining operations. News and financial services are analogous: again, a user interface, a background information gathering and filing service, and mechanisms that let a client register for, access and process interesting items. Cell phone systems often have similar components, either on the device or in the cloud. Browser extensions do too.
The project this semester will be much the same as in previous semesters:
build a networked three-tier application for any system that appeals to you.
This is a very open-ended specification, so the big problem is likely to be defining a topic of the right size. Almost every web service will suggest something, perhaps novel or perhaps "We can do that much better"; either would likely be fine. Hiding, selecting, or merging data from existing web services is a possibility; shopping, news and other bots are examples, as are the myriad mashups that combine information from multiple sources. Cell phone applications are often like this too, as are browser extensions.
Numerous web services (including Google, Amazon, and Facebook) provide program interfaces, which might be a way to put a different face on some aspect of their systems. Using these APIs could be good for potential projects, and creating a good API is a fine example of a non-graphical user interface.
Look around campus for other possibilities: maps, tours, notification services, databases, and so on are all potentially interesting and feasible, though make sure that the information that you want to use is available — concerns for privacy, property and turf can all get in the way of a great idea. You might find it helpful to consider the Princeton Data Sources that are available to you. Doing so might suggest project ideas, might help you to determine if your project idea is feasible, and no doubt will help you to access any Princeton data sources that you decide to use. We often hear about projects from staff, faculty, students, and external organizations. You might find something appealing on this list of Project Ideas from other people and by talking to people in other departments. If you want to explore further, come talk to the course instructors.
Some of the best projects come from noticing a task that is done by hand or poorly by machine, when it could be done really well by a suitable program, or where something complicated could profit from a neat user interface. Think about how rapid interaction might be used in some new system, or how some standalone program could be web-ified, or how some service could work on a phone. Or maybe focus on tools that make it easier to build such things, and create a couple of examples that demonstrate the wonders of your tools.
In our experience, in successful projects the people are really turned on by what they are doing, whether because it's their own idea and that's sufficient motivation, or because they are building something that someone else cares a lot about too. Either way, that kind of engagement usually leads to the best results. Be wary of projects where none of the team is really interested, or where one member is driving the whole thing, or where the system is too far away from your own experience.
Previous Projects have included web-based calendars and financial systems; numerous improvements of campus services and agencies; rental and exchange systems; course evaluation, selection and scheduling; information services for the local environment; social networks; and several map mashups.
The job is to create such a system, using any combination of existing tools and new code. The functionality that you must provide includes the following:
How big? There's no official requirement, but it ought to ultimately involve some thousands of lines of code of your own; churning out a thousand lines of repetitive JavaScript or mechanically generating a bunch of Python with Flask isn't enough. Some systems have been as big as 10,000 lines of Python; that's more than necessary, though it was great work. In any case, we will expect to see clean, well-written code, with appropriate attention to principles of sound software engineering.
Distributed or local? Your system must involve two network connections — one between the user interface tier and the processing tier, and one between the processing tier and the data management tier — so as to leave open the option of distributed operation.
Languages, tools and environment? You can use any combination that appeals for any aspect — web-based or stand-alone; Windows or Unix or Mac or phone; Java or Python or Javascript or C#; Ruby on Rails or Flask or Django; your own machine or a real server like Heroku, Render, or AWS. The only restriction is that your running system must be readily accessible so you can demo it effectively and we can run it for grading. We also require the use of the Git version control system and the GitHub repository service. They will save your life sometime for sure.
Build versus buy? Much modern software development is done by combining code and components that others have created. You can use as much of this as you like, as long as the finished product acknowledges the work of others, and has a substantial contribution of your own.
We have attempted to make this as open-ended as possible. This is your chance to invent something new, or to do something better than others do. You might think of this as practice for a new e-business or e-service, the sort of e-thing that made some of your predecessors here (like Meg Whitman and Jeff Bezos) into e-zillionaires.
But you have only about 12-13 weeks, so you can't get too carried away. Part of the assignment is to plan exactly what you are going to create, what each team member will be responsible for, and what interfaces you will require between components so independently-created pieces will fit together. What schedule will you follow? How can you work on different parts in parallel and keep them integrated? How will you ensure, if your time estimates are too optimistic (as they inevitably will be), that you have a working subset, rather than a non-working collection of partially completed pieces? How will you convince skeptical instructors that you are making progress, not just writing code (or doing nothing at all)?
Since the project will involve multiple people, a major task is to divide the work into suitable pieces, with planned interfaces. Each of these components must be a separate entity that can be implemented and tested separately. But you will have to think carefully about the interfaces between them: the problems caused by poor interfaces are a recurring theme in comments from previous projects (and, happily, so are the strongly positive experiences reported by teams that did a good job on interfaces).
The project will represent approximately 50 percent of your course grade. All team members will get the same grade (with the potential for a correction in the unlikely event of someone not carrying their fair share of the load), so be sure that you all agree on who will do what, by when, and to what standard. Each person must contribute their fair share, including writing a reasonable fraction of the code for the system, no matter what other role they play.
Here are some things you must think about at the beginning of the semester:
Since the project involves more than half a semester, it is possible to develop a significant piece of software. But serious planning and steady work will be required for your project to be completed on time. To encourage planning, organization and regular activity, the project will have several deadlines that will be enforced. [Some of the dates near the end may shift a bit; there will be adequate warning.] The TAs will be responsible for primary advisement of the teams and the lead instructors will act as backup and second-level advisement. You will be required to meet with your TA adviser on weekly basis; the course Schedule page provides details. These meetings are a graded component of the course, so preparation and attendance are mandatory — no excuses.
We will also try to follow good software engineering practice as much as possible. We will lean heavily on things that have been helpful in previous offerings, such as design documents, status reports and reviews aimed at helping you to organize and the instructors to monitor. All of these also are mandatory and graded.
The COS 333 ProjectFinder Application is a web application to help you find a project team. It also will help you to learn what other COS 333 students are doing for their projects, and will help other students to learn what you are doing for your project. To access the application browse to this address:
https://cos333projs.cs.princeton.edu
At the beginning of the semester, insert a row into the application to indicate your:
Then use the information displayed by the application to contact other students who have similar project interests or similar (or maybe complementary!) technical interests, thereby forming a project team. Repeatedly update your row as appropriate until your row is complete. Your row must contain a project name by the time of the next deliverable, the Project Approval Meeting with Instructors
You must insert your row into the Project Finder Application even if you already know which project you intend to work on. Remember that the purpose of the application is not only to help you find project teammates, but also to inform other students about what you are doing for your project.
Your team must meet with the course's instructors for about half an hour to discuss your plans before they are set too firmly. If you need help finding a topic or choosing among several, please talk to the lead instructor and TA advisers well before this meeting; we're happy to respond to ideas, make random suggestions, and help steer you, starting any time. But don't come to this meeting with two or three vague ideas, no team consensus, and no concrete plans. It is your responsibility to come up with a project and teammates, so don't leave this to the last minute.
If you want to do one of the projects described in the given list of project ideas, then you should contact the relevant organization as soon as possible. Usually each organization works with only one COS 333 project team, and usually decides to work with the first COS 333 project team that makes contact. Realistically you must have at least one meeting with the organization before your Project Approval Meeting; two would be better.
During the meeting the instructors may ask you these questions:
What is the name of your project?
What is your elevator speech, that is, your one-minute overview of your project?
Who will be your users? What are their names? Have they agreed to work with you? How many meetings have you had with them so far? How, and how often, will you communicate with your users throughout the project? Will there be different kinds of users?
What will your system do? How many user interfaces will there be? What are the most important scenarios?
How will your system work? What will be the nature of your user interface tier? A browser on a desktop/laptop computer? A browser on a mobile computer? A native Android application? A native iOS application? A desktop application?
What will be the nature of your system's data management tier? Generally, what data will your database store? Will your database be read-write or read-only? Where/how will you get the data to populate your database?
What will be the nature of your system's processing tier? What language will you use? What framework will you use?
Where will you deploy your system?
What are your milestones? What is your minimum viable product (MVP)? What are your stretch goals?
What risks will you face? What are your concerns about the project? What will you depend upon that is outside of your control?
These are some questions that your graders may ask themselves when grading... Did the team present a clear consensus idea with concrete plans? Was the participation among the teammates reasonably balanced?
Your team leader must create a Version Control Repository. You must use the Git version control system, and the GitHub web repository hosting service. Lectures provide details. Throughout the semester you and your teammates must store your project code in your Version Control Repository.
The name of your Version Control Repository must be the same as the name of your project, or at least must contain the name of your project.
Your Version Control Repository must be accessible to you, your teammates, and the course instructors. We recommend (but do not require) that your Version Control Repository be private, such that it is inaccessible to anyone other than you, your teammates, and the course instructors.
Use these GitHub usernames when making your GitHub repository accessible to the course instructors:
Your team leader must create a Google Team Directory. Throughout the semester you and your teammates must compose documents in your Team Directory. The documents that you and your teammates must compose are described below.
The name of your Team Directory must be the same as the name of your project, or at least must contain the name of your project.
Your Team Directory must be readable and writable by you and your teammates. The instructors must have read access to your Team Directory. Your team leader must tell the instructors the URL of your Team Directory by sending an email to cos333instructors@lists.cs.princeton.edu. Your Team Directory must be private, such that it is inaccessible to anyone other than you, your teammates, and the course instructors.
Use these email addresses when making your Team Directory accessible to the course instructors:
Your team must compose a Project Overview document in your Team Directory in a file named ProjectOverview. Your Project Overview must provide a thorough proposal of what you expect to accomplish in your project, and how. This must include an overview of what your system will do, the basic organization and components, a rough schedule of what you expect to accomplish each week, and who will be doing what. It must identify any significant risk factors and what you will do if bad things happen.
The purpose of the Project Overview is to encourage you to do some detailed thinking about what your project is, and how you're going to work on it. The more thinking you do ahead of time, the easier the pieces will come together when you do start to implement. Implementation before design is not a good idea.
The Project Overview must sketch out what you expect to accomplish in your project, and how. This must include an overview of what your system will do, the basic organization and components, a rough schedule of what you expect to accomplish each week, and who will be doing what. It must identify any significant risk factors and what you will do if bad things happen. ("We're expecting a large donation to buy a server; we will drop the course if this doesn't come through in time.")
The Project Overview must be roughly the equivalent of 3-7 printed pages. There's no need for fancy graphics or strong production values — the content is what counts, though a reasonable level of detail, perhaps some diagrams and screenshots, and good English free of typos and spelling mistakes will help suggest that you have taken some care with it.
The Project Overview must contain these sections:
Your project's elevator speech must be a single paragraph that states clearly and succinctly what your system does.
The idea is this: What would you say if you were alone in an elevator with Bill Gates for 60 seconds, and had to ask him for funding for your project?
The speech should be a short attention-grabbing description without big words but with good buzzwords. Essentially it should be a very terse summary of the information that you present in the following sections.
The Overview section must provide a general overview of what your project is, what it hopes to accomplish and the like.
The Requirements section must provide a few sentences describing the problem that your system will solve. More specifically, you must describe in detail the intended users of your system, how your system will benefit them, and contrast with existing solutions.
The Functionality section must provide scenarios that illustrate the major functionalities of your system. If you work through some scenarios carefully, the rest of the system will be a lot easier — this should be done before you worry about implementation details. Joel Spolsky's articles on specifications are worth reading for a general guide.
The Design section must declare the technologies that you intend to use in each of your system's three tiers. Will the user interface tier be a browser on a laptop computer, a browser on a phone, a native Android application, or a native iOS application? Will the processing tier use Python and Flask? Will the processing tier be deployed to Heroku? Will the data management tier use the PostgreSQL database management system? Will the database management system be provisioned through Heroku?
The Design section also must describe why you intend to use those particular technologies. If you will use a course "default" technology, then it might be sufficient to indicate that you chose the default simply because you have yet to find any good reason to use something else; but it would be better to provide a better reason if you can. If you will use some non-default technology, then you must provide a good reason for doing so.
Finally, the Design section must provide your database schema.
None of that is binding, but you must have thought seriously about it.
The Milestones section must begin with a description of your "MVP", that is, your minimum viable product. It also must list your "stretch goals" for your system, in the order in which you will attempt to achieve them.
Then your Milestones section must show your anticipated project schedule. That is, your Milestones section must list the significant milestones that you plan to achieve, and when you intend to achieve them, on a weekly (or near weekly) basis. Each milestone must be a concrete task or feature that is 100% done, not a vague description like "coding" or "debugging". Allow for slippage, and for all the required "overhead": demo, documentation, etc.
The Risks section is the place to show that you've thought about what you need to do and what might go wrong or cause delay. We're not interested in generic risks like someone getting sick, but in perils specific to your plan: learning new languages, tools, and systems; dependence on data or software or hardware acquisition. What will you do if your preferred path is blocked? Give this some thought, so you don't discover a month from now that you simply can't have something that you need.
These are some questions that the instructors may ask themselves when grading... Does the Elevator Speech section clearly and succinctly state what the system does? Is it compelling? Does the Overview section provide an overview of what the project hopes to accomplish? Does the Requirements section describe in detail the system's intended users and how the system will help them? Does the Functionality section contain a rich, specific set of scenarios that illustrate all/most of the system's functionality? Does the Design section describe the system's major components? Does the Design section describe likely implementation choices and the reasons for them? Does the Milestones section define the MVP and stretch goals, and does it list concrete tasks or features and specific times when they will be accomplished? Does the Risks section show evidence of serious thought about what could go wrong?
You must compose, incrementally throughout the semester, a Timeline document in your Team Directory in a file named Timeline. The Timeline must indicate, on at least a weekly basis, the tasks that each member of the team accomplished recently. You must update the Timeline throughout the entire project, including the reading period. You must review your Timeline with your TA adviser during each weekly status meeting.
The purpose of the Timeline document is to inform the course instructors not only about the team's progress, but also about the contributions of each team member. So it's insufficient to report in your Timeline document what your team, as a whole, accomplished recently. Instead each team member must compose a distinct paragraph describing his/her recent accomplishments.
These are some questions that the instructors may ask themselves when grading... Did the team keep the document current during the semester? Did the team review the document with its adviser at each weekly status meeting? Is the document current at the end of the semester? Does the document clearly indicate what each team member contributed to the project during each week of the semester?
Your team must have weekly meetings with your TA adviser starting after the Project Approval Meeting and through the last day of classes. In the first meeting you must go over the project in more detail, focusing on the system's users, the MVP, and the stretch goals.
Before each meeting with your TA adviser, you must strive to resolve any technical issues, so that you can show concrete progress since the last meeting, ideally a perpetually working system with a monotonically increasing set of features. The meeting with the TA adviser is a good time to discuss open issues regarding design choices, project evolution, and team responsibilities.
During meetings you must describe your progress since the previous meeting, as documented in your Timeline document, and as shown in your team's Version Control Repository. Given the short time scale, there really has to be progress every week. Your TA adviser will be looking for evidence that you're getting somewhere, though of course there will be setbacks and dead ends; we just want to make sure those are under control. Your TA also will be looking for evidence that each member of your team is contributing his/her fair share.
Our intention is that the meetings will encourage you to think about what you have done and what you're going to do next. The meetings are a chance to talk things through, and get advice and opinion from someone supportive who is looking over your shoulder. Your TA adviser's job is not to solve your technical problems, and it's certainly not to tell you what to do — it's your project. But pay attention, especially if your TA adviser is concerned about something.
Everyone must come to all meetings if at all possible. If you absolutely must be away, courtesy and a concern for your grade mandates sending an explanation well before the meeting. Unannounced absences, and especially total no-shows, are unacceptable.
Be prepared. You might find it a good idea to meet among yourselves the day before your TA adviser meeting. The time you spend thinking about and organizing for your meeting will pay off. Your TA adviser will be looking for you to be obviously prepared, with an organized agenda, and volunteering information; your TA adviser should not have to drag things out of you, and will definitely be unhappy if you're clearly just winging it with no evidence of effort ahead of time.
Your team must develop, and demonstrate in your weekly meeting, wireframes of your application. Your wireframes should consist of screen sketches. Collectively the screen sketches should form storyboards which indicate how users will interact with your application.
Your wireframes may be "low tech." For example, you may express your wireframes as pencil-on-paper sketches (for desktop/laptop computers) or maybe as pencil-on-index-card sketches (for smart phones). A step up would be to use PowerPoint or Google Slides; the advantage would be that your wireframes would be more readily shareable among your teammates. However, we believe you will find it convenient to use a more "high tech" approach via a wireframe creation tool. Wireframe.cc is a pleasantly simple one. Figma is more popular and powerful, but also is more complicated. Both Wireframe.cc and Figma offer free tiers and good web tutorials.
After creating your wireframes, and ideally before you present your wireframes in your weekly meeting:
The people from Princeton's User Experience office create a Wireframe Design Review Notes document. You should study that document before meeting with them, and should bring a copy of that document with you to your meeting. It would be helpful to student that document even if you decide not to meet with them.
The course instructors understand that changes to your user interface probably will occur as your project unfolds. And so your wireframe probablly will become stale. Nevertheless, you should try to make your wireframe accurate and detailed. Getting the interface (close to) correct early in the project will pay huge dividends later.
Your team must develop, and demonstrate in your weekly meeting, a bare-bones prototype that shows approximately what you are trying to do, what your system's core components will be, and how they will communicate with each other. It need not do much, but it must demonstrate end-to-end connectivity and do some minimal part of the job. Each member of your team must be able to build and run your prototype system on his/her local computer.
Your team must develop, and demonstrate in your weekly meeting, an "alpha" version — an almost working version of the core functionality of your project. "Core" means the basic operations that form the essence of your project; if you were doing Amazon 2.0, for instance, this might mean searching for books and accepting orders. "Almost working" means that wizards (you) can help experienced programmers (us) to use the system. Your system may crash and need restarting or suffer other bugs and stability issues.
Most teams plan to deploy their systems — to Heroku, Render, cPanel, AWS, or some other application hosting service. If your plan indeed is to deploy your system, then your alpha system must be deployed. More specifically, most teams plan to deploy their databases to Heroku, Render, ElephantSQL, or some other database hosting service. If your plan indeed is to deploy your database, then your alpha database must be deployed.
Your alpha version must be able to convince us that your project can be completed by the deadline.
Your team must develop, and demonstrate in your weekly meeting, a "beta" version of your system. The beta version must show that all core features work, and all intended features must be installed and implemented, though not necessarily complete or stable. No major component must still be in stub form — this is the "drop date" for features that have not been implemented. Your system at this stage must survive casual experimentation without guidance or hand-holding. Your TA will "do the driving" during the demonstration.
Your team must give a 20 minute public presentation of its work during reading period week. All team members must attend the presentation. The presentations will be clustered into sessions, with two or three presentations per session. You must attend the other presentations in your session, for instruction and moral support.
The presentation must include a live demonstration of your work. The presentation will determine a significant portion of your grade, so you (and we) want it to go as smoothly as possible. In order to assure this, start thinking about your presentation early. You could picture your presentation/demonstration as an event that will make or break your "company" — you'll be on the spot in a foreign place, with an audience, though the audience is really just a group of very supportive potential customers, investors, friends and family. As to content, the "trade show" metaphor is useful, but you must aim for more than just a glitzy demonstration — you must also spend at least some time discussing the architecture, the trajectory of the project, and providing evidence that you learned something.
One possible outline of your presentation would be: a short introduction of what your system is supposed to do; a demonstration of its most important features; a summary of other features; an overview of the system's architecture and implementation, especially showing the system's database schema; an anecdote of something that worked well or failed disastrously such that you were able to take something away from the experience; and something that you might explore further or do differently if you were to start all over again or had more time.
You will be allotted 20 minutes, which is not a lot of time. Plan on using about 15 minutes, to leave time for questions, setup and teardown, and other delays. In previous years teams have done well on timing; rehearse to keep the streak alive. Plan demos that do not require much typing or mousing or window-switching — this invites things to go awry, and invites the audience to get restless while you poke around. You just don't have enough time.
Have fun. The projects are really interesting, and the enthusiasm of their presenters helps make that evident to all in attendance. Because a healthy audience amplifies that enthusiasm, each student is required to attend the other presentations in the same session and you are strongly encouraged to attend more, for edification and moral support. Visitors are welcome, so bring your friends and family. Typical projects are great; come and hear about them. We will advertise the schedule of demos in advance.
Your team should compose slides to support the presentation. You must place the slides in your Team Directory in a file named Slides.
These are some questions that the instructors may ask themselves when grading... Did the team motivate the system well? Did the team provide a good overview of the system? Did the team describe and demonstrate the system's core functionality well? (We're expecting a real-time demonstration; you should give a recorded demonstration only if there is a compelling reason to do so.) Did the team provide a good description of the system's design at an appropriate level of detail? Did the team describe what went well during the project, and what should have been done differently? Did the team provide evidence of learning? Did the team allow time for questions? Did the team answer questions well? Was the presentation reasonably balanced among team members? Did the presentation consume roughly 20 minutes?
Your team must compose a Grader's Guide document, and place it in your Team Directory in a file named GradersGuide.
Your project will be graded by at least two people: your TA adviser and an undergraduate grader. Your Grader's Guide must tell your graders what your system does and how to get your system to do what it does. It must describe all (or at least most) of the features of your system in enough detail that your graders know of their existence, and know how to give them a try.
If you must make assumptions about your graders — for example, that they use Google calendar, use Facebook, have an Android or iOS phone, use a smart phone contacts list, and so forth — then discuss those assumptions with the instructors before composing your Grader's Guide, and state those assumptions explicitly near the beginning of your document.
Your Grader's Guide must begin with a short introduction of your system. After the short description your Grader's Guide must contain a table of contents listing the titles of your use cases. The table of contents must be of this form:
Use Case 1: Some title that defines a goal Use Case 2: Some title that defines a goal ...
After the table of contents, your Grader's Guide must contain your use cases. Each use case must begin with the title of the use case, as provided in the table of contents. Each use case must provide instructions on how your grader should interact with your system to achieve the stated goal. To grade your system, your grader will perform the instructions for each use case precisely as described in your Grader's Guide. Your grader will perform the use cases sequentially; so you must assume that the state of your system at the beginning of use case n is the same as the state of your system at the end of use case n-1. After your grader is finished performing all of the use cases, your grader may perform additional testing.
Each use case must be concrete. For example, don't write "Click on the Save button and then enter a file name." Instead write "Click on the Save button and enter the file name 'myfile1'." Don't write "Enter a username and password." Instead write "Enter username xxx and password yyy".
Each use case also must be specific; each use case must illustrate one logical path through your system. For example, don't write "At this point you can either click on the Add button to add a new entry, click on the Delete button to delete an existing entry, or click on the Edit button to edit an existing entry." Instead write "Click on the Add button to add the entry named xxx." Then compose an additional use case to illustrate how to delete an existing entry, and an additional use case to illustrate how to edit an existing entry.
The first use case must be entitled "Accessing the system" (or something like that). It must give the graders instructions on how to access/create/install your system. If your system is a web application that is hosted in the cloud, then the first use case will be easy to compose. If your system must be installed on the grader's computer or smart phone, then the first use case might be difficult to compose.
Some use cases might make sense only if your system already contains data for the particular grader. In that case, pre-populate your system's database with those data for the particular grader.
Your graders will not work together; one will run your system before the other runs it. So make sure that the instructions in your Grader's Guide handle the sequential running of your system. For example, make sure that your database need not be reset after the first grader runs your system and before the second grader runs it. Or, if your database must be reset, then tell your graders in your Grader's Guide to contact you when it's time to do the reset.
Collectively your use cases should cover all, or at least most, of your system's functionality. It would be reasonable to add a final Additional Functionality section describing non-mainstream functionality of your system that you reasonably couldn't illustrate through use cases.
Your Grader's Guide is the most important document supporting your system. It's especially important that your Grader's Guide be correct. If it's incorrect, then your graders won't necessarily know if the error is in your Grader's Guide or in your system. In either case, regrettably, your grade would be penalized.
These are some questions that the instructors may ask themselves when grading... Does the document describe what the system does and how to get it to do what it does? Is the document complete? Does the document contain a table of contents listing use cases? Does the document contain concrete use cases that describe how to use the system? Does the first use case describe how to access or create/install the system? Do the use cases cover all (or at least most) of the system's functionality? Is the document correct? Is the document clear? Can we understand and perform the instructions within each use case?
Your team must compose a Product Evaluation document in your Team Directory in a file named ProductEval. Your Product Evaluation must present your evaluation of your final product. It should have three sections.
The first section must cover testing. It must answer the question: "To what extent does your system behave as you intend it to behave?" The document must describe how you went about testing your system. The description must be structured using the testing taxonomy described in lectures and referenced by the assignment specifications. What internal testing did you do? What white-box external testing (boundary testing, statement/coverage testing) did you do? What black-box external testing (use case testing, stress testing) did you do? What test automation did you do? Your graders won't expect you to have performed testing in all of those categories. (Test automation is particularly difficult to do for graphical systems.) But your graders will expect you to address each category explicitly. The section must end with a description of which aspects of your product are robust and which are fragile, and must provide a list of all bugs that you found through your testing but have not yet corrected.
The second section of the document must cover evaluation by users. It must answer the question "How well does your product meet the needs of its users?" For this section you must conduct formal evaluations of your product involving "real" users. You must compose tasks, present the tasks to typical users, observe the users as they used the system to perform the tasks, encourage the user to talk aloud while performing the tasks, take thorough notes, and report a summary of the results. Include the task list and your complete notes in an appendix.
The third part of the document must cover evaluation by experts. It must consist of your own formal evaluation of your product using the heuristic evaluation technique. Optionally, you also should evaluate some important parts of your product using the cognitive walkthrough technique. Both heuristic evaluation and cognitive walkthrough are described in lectures.
These are some questions that the instructors may ask themselves when grading... Does the document answer the question "How well does the system work?" Does the document describe how the team tested the system? Does it describe the results of the testing, that is, which parts of the system work well and which do not? Does it list all known bugs? Does the document answer the question "How well does the system meet the needs of its users?" Does the document contain an evaluation of the system by typical users? Did the team compose a task list, present the list to typical users, observe the users as they used the system to perform the tasks, encourage the user to talk aloud while performing the tasks, and take thorough notes? Does it include the task list in an appendix? Did the team perform a heuristic evaluation of the system, as defined by Nielsen? Less importantly, did the team perform cognitive walkthoughs of any parts of the system?
Your team must compose a Project Evaluation document in your Team Directory in a file named ProjectEval.
The first section of the Project Evaluation document must describe how the project worked out. How good was your original planning? For example, you might comment on... How did your milestones go? What was your experience with design, interfaces, languages, systems, testing, and so forth? What surprises, pleasant or otherwise, did you encounter on the way? What choices did you make that worked out well or badly? What would you like to do if there were more time? How would you do things differently next time?
Imagine that you are composing this section for your (friendly!) boss or professor and want to explain what you learned that could be applied to the next project. Some teams present a single unified section, synthesized from the thoughts of all team members. Other teams prefer to compose separate pieces of the section, since they focused on different project components and learned different things. Either is fine, but in both cases aim for true introspection: try to avoid repetition or banal generalities like "this was really interesting and we learned a lot".
Second section of the Project Evaluation document must describe some interesting technical problems that your team encountered during the project and how you solved them.
The third section of the document must acknowledge the software that your team used that was composed by others: Flask, Jinja2, jQuery, React, Bootstrap, Render, Heroku,and so forth. If you used technologies that were not covered in lectures, then it would be appropriate to include short descriptions of those technologies. The section also must acknowledge sources of information that your team used — documentation websites, tutorial websites, discussion websites, books, and so forth — that were particularly helpful.
These are some questions that the instructors may ask themselves when grading... Does the document describe positive and negative aspects of the project experience? Does the document describe what the team members learned from the project experience? Does the document describe some technical problems that the team members encountered and how they solved them? Does the document acknowledge the use of software written by others and major sources of information?
Your team must create a directory named src in your Team Directory, and must copy all source code to your src directory. That includes anything you created, especially source code and similar material. If you have help files, images, data, and so forth, put them in the src directory too. Sub-directories are fine. Do not include other files that are created by compilation or downloaded from somewhere else: no object files, executables, class files, Git control files, etc.
Be sure that your code is complete before you copy it to the src directory. Your graders will be looking through your source code to get an idea of what you did and how well you did it, so everything must be there.
Your final product is due at 5:00PM on the Dean's Date. For web apps, this means that we need the final URL and that the site needs to stay live for approximately two weeks beyond Dean's Date. For device apps or other stand-alone programs, this means that you may need to lend your graders a device, or maybe meet with your graders to do a demo on your device.
Grading for the project will be based on a number of criteria, including your:
You are encouraged to ask questions that will help clarify things for everyone. Murphy's Law applies to projects and their administration, so there undoubtedly will be screwups. We apologize for those in advance, but of course they too will be a simulation of reality.
This page was written by Brian Kernighan and Robert M. Dondero, Jr.