Project deliverables 

Here is the outline of the project structure and the deliverables at various milestone of your project. The subsections further down explain each deliverable in detail. Note that in this project, we ask you to document the project as if you are going to hand over the project to another team after the next milestone. This is so that you have a specific target audience when you write project documents.

• During the initial period you will do two coding exercises to prepare yourself for the project.
  
• Individual coding exercise - to freshen up your coding skills. You can start this before you team up.
  
• Team coding exercise - to get used to working in a team. You need to team up before you do this exercise.
  
• Next, you will specify what you propose to build and at what point you will deliver which features. This will result in the following deliverable.
  
• project manual V0.0
  
• Iteration 1 comes next, in which you implement the set of features you promised to deliver first. Deliverables at the end of this iteration are
• product V0.1
  
• project manual V0.1
  
• During iteration 2, you will improve the functionality delivered in the previous iteration and add some more functionality. Deliverables at the end of this iteration are
• product V0.2
  
• project manual V0.2
  
• project demo
  
• After you finish iterations 2, you will have a little more time to finish your individual report about the project.
  
• individual report 

Please see the course schedule to find out submission deadlines.

Project manual V0.0

As explained in the previous section, you will write this document as if it will be given to another team to develop the product. That is, the intended audience for this document is another team that will depend on this document to tell them what to build. The document contains just enough information required for them to take over the project. The basic questions you should ask yourself when writing this document are:

• What do we know about the system at this point?
• Which part of that knowledge will be useful for the next team who will be taking over?
  
• What is the best way to pass that knowledge to them?
  

For example, this version of the document can contain,

• a description of the product you plan to build. In this version of the document, you may describe just a "minimal" version of the product in detail. You can call this V0.0 of the product. This description can go beyond the minimal version if you want, but this is not required.
  Things you can consider for such a description include the below. Note that you are not required to include them all. Neither you are restricted to what is listed below. 
• textual descriptions (e.g., An overview section)
  
• domain models
  
• use cases (diagrams, descriptions)
  
• glossary of terms
• UI prototypes
• supplementary requirements that are not captured elsewhere E.g., constraints, business-rules (business rules are policies, procedures and constraints that are present in the problem domain. In our case, this translates to rules you want to enforce on your product e.g., The same puzzle should not appear more than once within 100 game plays).
  
• A feature list for V1 (i.e., the first public release) - specify "minimal", "typical" and "unique" features (i.e., we go beyond the "minimal" version here) you have in mind for the product. This shows your vision for the final product. Just a brief description should be enough. But you may describe in more details if you wish.
• Minimal features (aka "essential features") : without these features, the product looses its essence. E.g., Timing is not a minimal feature for Sudoku as Sudoku without timing is still Sudoku. A number grid on the other hand is a minimal feature for Sudoku.
  In this project, we plan to implement all minimal features.
  
• Typical features (aka "so what? features"): Most similar products have these features although they are not essential. Not having them may upset some customers, but having them is unlikely to excite most customers. E.g., Save game, High score board.
  In this project, we plan to implement only a small sample of typical features. You may schedule the rest of the typical features beyond V0.2.
  
• Unique features (aka "killer features"): These are the selling points of your product. They should be exciting enough to make your product stand out from the rest, at least for a certain market segment. E.g., a voice controlled Sudoku for physically challenged people. 
  In this project, we plan to implement at least one unique feature. You may propose as many of these as possible as long as they make sense in the long-term plan for your product (i.e., beyond V0.2).
  
• A high level delivery schedule - identify which features you will deliver in V0.1 and in V0.2. 

Use this file as the starting point of your project manual. All project documents submitted should be in MS World format (*.doc or *.docx). See here if you are not sure of your team number or the supervisor (supervisor is often your tutor, not the course lecturer). 

page limit: 5 (why do we have a page limit? see the FAQ below)

submission: Name the file as "["team number"]["Version number"]".doc/.docx (e.g. [C13][V0.0].doc) and upload to the "[V0.1] Manual" IVLE folder. Please follow the naming convention precisely as we subject your submissions to some automated processing. Project documents are team submissions; no need for each team member to submit duplicates.

evaluation: We use this document to see whether you know how to document software requirements. We also want to know whether you have chosen an appropriate set of features to deliver at milestones V0.1 and V0.2. You are cautioned against promising too many features too early. One well-implemented feature will earn you more marks than two half-baked features. We also check how well you have communicated the information required to easily takeover your project by another team. Grading will be on  K/K basis.

Product V0.1

This is a working system containing the functionality you promised in project manual V0.0 to deliver at this milestone.

submission:
Zip up the following files, name it "["your team number"]["version number"]".zip (e.g., [Q12][V0.1].zip), and upload to the "[V0.1] Product" IVLE folder. No *.rar files please.

• Source files (please remove unnecessary/unused temporary files etc.).
  
• An executable version of your system.
• A readme.txt describing how to start the program.

Upload a 2 minute screen recording of a product demo to the "[V0.1] Video" IVLE folder. Name the file using your team number. e.g., [C12][V0.1].mpg. You can use free tools such as Screen2exe , Debut or Jing for screen-recording the demo. Let us know if you know of a better screen recording tool that is free. Just a screen recording is enough. Text annotations and voice narration are not necessary (but OK to have). Note the 35Mb upload limit imposed by IVLE (hint: Screen2exe produces very small files).

evaluation: In this submission, we check whether you have delivered what you promised in project manual V0.0. To earn full marks, you should have at least a playable minimal Sudoku game. Grading will be on  K/K basis.

Project manual V0.1

This is an *improved and updated* version of the previous version of this document. Imagine you are handing over the project to another team at this point. This new team has never seen your previous version of the document and will rely totally on this version to understand the project. You have total freedom over what to include in this version of the document. However, given the purpose of the document, we think you will choose to repeat a refined version of most of the stuff you put in the previous version of the document.

Given below are some things you could consider adding to it. Note that you are not required to include them all. Neither you are restricted to what is listed below.

• Architecture
• important APIs
• Design descriptions (sequence diagrams, state diagrams, notable algorithms ...)
• Instructions for installing
  
• Instructions for testing
• Instructions for running the application
• User manual
• Change history (you can use this section to show how you improved the project manual and the product itself over time. hint: also state why you did each change).

Use this file as the starting point of this document.

page limit: 15

submission: Similar to previous version of this document.

evaluation: Similar to previous document, we check how well you have communicated the information required to easily takeover your project by another team. We also check how well you have responded to our feedback on the previous versions of the document. Grading will be on   K/K basis.

Product V0.2

This is a working system containing the functionality promised at this milestone. It contains an improved version of the functionality delivered before as well as some new functionality.

submission: Similar to previous version of the product. Screen recording can be slightly longer.

evaluation: Based on a demo and Q&A session. The whole team is required to be present. Not on K/K basis (as this is your final submission, stricter grading criteria will be applied). To earn a B+ level score for the project, you should have at least some typical features and at least one unique feature.

Project manual V0.2

This is an updated and improved version of the previous version of the handover document. It now describes the system at this milestone. 

page limit: 20

submission: Similar to the previous version of the document.

evaluation: Similar to the previous version of this document, but not on K/K basis (as this is your final submission, stricter grading criteria will be applied).

Individual report

This document describes how you applied to the project what you learned in the course. We hope having to write this document will encourage you to consciously apply software engineering theories to you project instead of treating it as a mere programming assignment.

It also serves as a record of how exactly you contributed to the project. It is one more means for us to make sure you did your fair share of the project work. Be sure to include all things your individually contributed to the project. Any task done together with other team mates can be included as long as you clearly specify who else was involved and what your part of the task was. Please note that we release your individual report to the whole class after you submit it.

Regular note keeping (a kind of a "journal") during the project can help you write this report easily.  Use this file as the starting point (it includes some sample contents) when writing this report.

You can strengthen your individual report by adding an appendix (not counted for the page limit). It could contain things like
- A sample of code your contributed to the product (not longer than 2 pages)
- A sample of documentation you contributed to the project manual
- A sample of a diagram you contributed to the project manual

page limit: 5

submission: To the corresponding IVLE folder. Name the file "["team number"]["matric"]["Name"]IR".doc/docx. (e.g., [C13][U060577T][Peng Bo]IR.doc)

evaluation: We evaluate this document based on how well you have applied theory to the project. In addition, we may use this to judge the size of your contribution to the project (if required).

Forming teams

• Team size is 4.
• We recommend (but do not insist) that you form teams within the same tutorial group. Such teams have more contact opportunities with team mates and the supervisor.
• If the above is not possible, try to form a team among those who are under the same tutor. Please see the "Teaching Team" page to find out which Tutor is taking which tutorial.
• If you insist on forming a team across tutors, we will not stop you. Such teams typically have the least contact opportunities among team members and with the supervisor. So you should have a VERY good reason for forming such a team.
• After forming a team, please inform your tutor. If you have trouble finding teammates, you can use the "Project discussions forum" to get in touch with others looking for a team. Tutorial 1 is another good opportunity to form teams. If you still cannot find a team after tutorial 1, please inform your tutor.
• Please make sure the whole team agree on what language to use for the project.
• You may elect one of your team mates as the team leader. However, this is not a requirement.

Supervision

You may meet your supervisor as many times you need, subject to flexibility in the supervisor's schedule. Please make sure the whole team meets with the supervisor at least two times (including feedback sessions for your intermediate submissions) before your final submission.

Please note that it is not the supervisor's job to chase you down and give help. It is up to you to get as much guidance from the supervisor as you need.

Teamwork

We expect each team member to do a fair share of the project work. We will penalize those who did not did their share of the work. Some situations where you are very likely to be penalized...

• You did not do any coding.
  
• You did all the coding yourself (If you strongly feel that none of the other members write "good enough" code, please get permission from the supervisor before taking over the whole coding aspect).
• You regularly missed team meetings.
• You regularly did not deliver what your promised.
• You often did not adhere to team decisions and regularly took critical decisions on your own without consulting the team.
  

We use several rounds of peer-evaluations and the individual report to verify that everyone did a fair share of the project. However, please alert the supervisor early if you think someone in your team is not pulling his/her weight and does not respond to your friendly reminders to do more.

Plagiarism

We publish (i.e., make available to the whole class) most of your project submissions. While the main objective of this to let you learn from each other, it also acts as a very effective deterrent against plagiarism. If you copy from another team, it is very likely that someone else in the class will notice this and report to us even if we failed to notice it ourselves.

However, you are allowed to use ideas from other teams, subjected to the below guidelines.

• Do not copy things such as code and document fragments "wholesale" from others. Instead, adapt others' ideas to suit your context.
• Clearly mention such adoptions in your project manual. State from whom you adapted the idea, what was your original idea that is being replaced, and why you think the new idea is significantly better than your own original idea.
• You can only use ideas taken from "published" submissions. Teams are not allowed to share things directly among each other.

If you want to use things from elsewhere (e.g., third-party libraries), please seek your supervisors permission first.

Programming environment

We recommend you use either Java or C++ for the project. Please seek permission from your supervisor if you want to use another language.
While you may use any platform (Windows, Mac, Unix, ...) for development, your submitted system should be compatible with Windows.
We give some extra help (see the resources page) on using the Integrated Development Environments (IDEs) Eclipse and Visual Studio. However, it is not compulsory to use any of them.

Tech help

In this semester, we have roped in couple of your seniors to help you in technical difficulties related to Java, Eclipse, C++, and Visual Studio. If you need their help, please post your problem in the "Java tech help" forum or the "C++ tech help" forum in IVLE. You are discouraged from contacting the tech experts directly. This is so that whatever help being given is given openly so that other classmates can benefit from it. A solution is not guaranteed. However, they will do their best to help you. 

In addition, we have prepared some supplementary materials to help you along in the technical side of the project. You can find them in the resources page.

Grading

The project accounts for 30% of your final grade. See the "Admin info" page for more details.

We use the K/K mode grading for intermediate submissions. Given next is an explanation of what K/K mode grading is.

K/K mode grading

We use K/K mode of grading during early stages of the project. This mode is suitable when learning from mistakes is more important than assessment.

• In this mode, we give full marks if we see evidence of "genuine effort", although the outcome may not be "optimal" in the eye of the evaluator.
  
• We give a "Kita" if we cannot see a genuine effort. A Kita means "you are in danger of getting 0 for this submission, unless you improve a lot in the next submission".
  
• Kita receivers can still earn up to 100% of the marks for that submission if they do a good job in the next submission. 
• We give a "Kudos" for those who did a great job, at least in some aspect of that submission.
• Both Kita cases and Kudos cases are reviewed by the whole teaching team so that there is uniformity across the class.

In summary

• if you didn't hear from us, you did an OK job and you get full marks.
• if you received a Kudos, not only you got full marks, but also, we think you did a great job.
• if you received a Kita, you can still earn up to 100% of the marks if you do a substantially better job next time. If not, you will get zero marks.
  
  

This mode of grading has the following benefits:

• It reduces the subjectivity of grading, especially when multiple evaluators are involved.This is because most of the class receives the same grade.
  
• It gives negative feedback when necessary without demotivating you too much. You can recover from a Kita without loosing any marks.
  
• It does not promote unhealthy competition among project teams during early stages of the project. That is because you need not be the "best in class" to earn full marks for a submission. However, those who are genuinely motivated will work harder to earn "Kudos".
• It gives slow teams a chance to catch up.
• It fits "no right answer" situations and "learning from trial-and-error' situations such as SE projects.

FAQ

• Why do we have strict page limits for document submissions?
  Most software engineers hate writing and reading documents. By setting a page limits we want to encourage you to write shorter documents that contain just enough contents to communicate effectively whatever that you are trying to communicate. We do not read beyond the page limit unless what we have read up to the page limit makes us want to read more.  Therefore, it is in your interest to stick to the page limit. But if you think you have more good stuff than that would fit in the page limit, go ahead and include them by all means.
  
  
• Why don't we specify what exactly to put in submission documents?
  Because the best way to communicate something often depends on what is being communicated. Therefore, we aim to iterative refine project documents. We believe the learning experience will be richer if we let you decide yourself the best way to present your project information rather than just following our instructions blindly.
  
  In real-life projects you will not be told which diagrams to draw; that is a decision you have to make yourself.
  
  
• Why do we number releases 0.1, 0.2 etc. instead of 1.0, 2.0 etc.?
  Because what you do in this project is meant to be a small part of a bigger project and you are doing only the initial steps of that project.
  
  
• Why do we grade initial submissions for effort rather than quality?
  Because we want you to learn from your mistakes without incurring penalties for doing so.
  
  
• Doesn't publishing submissions unfair to the team who submitted them?
  

• Must we have a GUI for the product?
  Whether to make your UI textual (menu-based or command-based) or graphical depends on the type of the product. Often products have both textual UIs and GUIs. However, you can defer the implementation of the GUI to a later iteration to be done by the team that will take over the project after you. Treat the GUI as just another feature that you deliver at some point in the project.
  
  
• Why do we have a background story?
  It gives you a real-world context to base your decisions. For example, instead of asking us "should we have a GUI or not?" you will be asking yourself "if the we are releasing this to the public as per our background story, does it make sense to release without a GUI?".
  
  
• What do I do if my question is not found in this FAQ?
  Use the IVLE project forum or IVLE anonymous feedback feature to ask your question.
  
  
• Why only 30% for the project? How come the final paper has 55%? Isn't SE is about practice and not so much about theory?
  
  As per our curriculum, CS2103 is primarily a theory course, focusing more on modeling and design and less on implementation. You get to apply the theory learned here in CS3215 (8MC, 6-person team, big project, soon to be converted to an year-long project).
  
  Facts: This is a team project. You don't have much experiences in team projects. We don't have enough manpower to track each of you individually while you work as part of a team (we do that in CS3215 where the class size is smaller).
  
  The % for the CS2103 project used to be even lower. We kept increasing it over time, but now we have reached a point where it shouldn't be increased any more. Here's why:
  
  Imagine we allocated 60% for the project. Also imagine you are an A+ student new to SoC (some of you are), you have no friends here, and you ended up in a lousy team. Your project turned out to be a total disaster (you tried your best, but others screwed it up anyway.) and scored only 10%. No matter how well you do the final paper, you will not get more than a B instead of the A+ you really deserve. Imagine how demoralize you would be. We want to avoid this situation at all costs. You will realize the value of this protection only if you got caught in such an unfortunate situation yourself.
  
  On the other hand, what is the worst that could happen if the project is only 30% and you put in an effort worth of 60%. Your extra effort will be rewarded just the same, you just don't realize it :-) Not only you will earn a very high score for the project,  you will do much better in the exam because some of the exam questions purposely cater for those who did a sincere job in the project (aha! you didn't know that right?). Those who studied just the theory will not score as high as you in those questions. So in reality,  project counts for more than 30%, but some of it is hidden in the exam paper.
  
  Furthermore, this project is small enough so that someone with good programming skills can still produce a good product without applying good SE. However, we do not want such students to earn an A+ just on the strength of good programming skills.
  
  
• Why only 5% for CE1+CE2+V0.0+V0.1?
  At first, this appears unfair to those who work hard for intermediate submissions. Alternatively, it might tempt you to do very little during V0.0 and V0.1 because "marks allocated" is usually taken as a measure of the "expected effort". Nevertheless, there are many good reasons behind this decision. Here are some of them:
  
  First and foremost, intermediate submissions are for you to make mistakes and learn form them. It is also for us to give you feedback (both negative and positive) without hurting your grade. They are not meant as evaluation tools. Therefore, you are given full marks unless you do a really lousy job, even that will be after giving a Kita first.
  
  The "marks==effort" rule is less applicable here because these are *intermediate* submissions. You are developing only one product for which you should be rewarded only once. What happens to the stuff you produce in V0.0 and V0.1? You will keep the good stuff and submit them in V0.2. You will throw away the lousy stuff (without any penalty). So all the good stuff you produce will actually earn marks they deserve at V0.2. Giving more marks for them at V0.0 and V0.1 will be double/triple counting.
  
  What will happen if we allocate 10% for CE1+CE2+V0.0+V0.1 instead? Almost every team will get full 10% for these anyway (they are for learning and for getting feedback, not for evaluation, remember?). It will simply push the grade cut-off up by 10% without affecting anyone's grade. What's worse is we now have only 13% for the V0.2. Since in the current scheme we only give 5% for CE1+CE2+V0.0+V0.1, we have 15% to play around with during V0.2. We can use it to give good teams a much higher mark than an average/poor team.
  
  Consider this situation:
  Lazy team: does a minimal job for V0.0 and V0.1. Try hard for for V0.2, but due to lack of effort in previous iterations, ends up producing an "OK" product. Gets 5%+5%+2% = 12%.
  Good team: doesn't care about low % allocated to intermediate versions. works hard all the way and produces a great product. Gets 5%+20%+5%=30%. A clear 18% ahead of the lazy team, and deservedly so. The gap won't be so big if we allocated more marks for immediate versions, right?
  
  To relate our rationale to real life, will the customer pay you for producing intermediate versions? Getting the customer to help you by giving feedback for intermediate versions is a sweet deal already. If you try to get money for intermediate versions, you will loose the contract :-)
  
  To sum up, we are not "ripping you off" by giving low marks for intermediate submissions. Most of the work you do for intermediate submissions is the work you have to do anyway even if we didn't have intermediate submissions. You will get marks for them eventually. Besides, having intermediate submissions helps you to discover problems (e.g., lousy team members) early and gives you a better chance of solving them. On the other hand, the time and effort *we* put in to handling intermediate submissions is our "gift" to you (we didn't *have* to do that you know :-) getting rid of intermediate submissions will make our life much easier). The 5% you get for intermediate submissions is an additional bonus.
  

Edit this page (if you have permission) |

Google Docs -- Web word processing, presentations and spreadsheets.