Report #1: SYSTEM SPECIFICATION — Iteration 1(a) — (due date given here)
This report shall be submitted in three steps:
1. Part 1 (Section 1 Customer Statement of Requirements and Section 2 System Requirements)
2. Part 2 (Section 3 Functional Requirements Specification and Section 4 User Interface Specification )
3. Entire Report #1 (all sections included)
This document is known as Requirements Analysis Document (RAD). Also see the successive Report #2: SYSTEM DESIGN.
Note: Keep this report for future reference because it will become part of your final report (Report #3). This report should be revised, updated and/or corrected on a continuous basis, so that an improved version becomes part of Report #3.
Note that, unfortunately, the following generic format will not fit well all projects. Different projects will require different distribution of effort for Section 3 Functional Requirements Specification and Section 4 User Interface Specification. All projects require both sections, but their focus may be shifted. Some projects must focus on their system’s functional behavior (Section 3). Such projects include parking garage automation, restaurant automation, traffic monitoring, and the investment game.
Other projects shall focus on the user interface specification (Section 4), particularly projects that develop a video game or biology labs. Their use cases may be relatively simple.
Finally, some projects will have relatively simple use cases and the user interface, but will focus on sophisticated simulation algorithms. An example is the Minority Game. They shall have detailed description of their algorithms in Section 5.c Mathematical Model of their report.
While preparing this report, you may wish to check the grading checklist and avoid some typical mistakes in your report.
The report must contain the sections listed below. Each section should be clearly delineated, with its own heading and pagination. The sections should be numbered as below, to facilitate the grading process.
A minimum 3-page customer statement of requirements is required (Section 1.a). Your customer statement of requirement must describe customer’s requirements or expectations from your system, instead of listing the features that reflect the thought and analysis of the system developers. The Customer Statement of Requirements must be written from the customer’s point of view rather than the developer’s. You should describe informally, without the use-case jargon, the motivation for your project, what kind of problem you are solving, and how this problem is solved in the current practice (before your proposed system is deployed). Use the customer’s language and terminology, i.e., the language familiar to your target users, and avoid technical jargon. Utilize charts, illustrations, and screen mock-ups to make it easier for the reader to understand the problem. Provide references (books, papers, websites) where to find more information or see existing solutions. Examples customer statements of requirements are given in the descriptions of software project ideas.
Ensure that the enumerated requirements in Section 2 capture all features of the system mentioned in the narrative of Customer Statement of Requirements (Section 1.a).
Missing or incomplete enumerated list of requirements makes it difficult to establish the mapping between requirements and use-cases (i.e., traceability).
This omission, in turn, makes it difficult to understand the true scope of the project. You must show a clear relationship between the fully dressed use-cases and the customer requirements.
Show and discuss how specific requirements are addressed in the associated use-cases.
Your requirements should be testable—write the acceptance test cases to show how your requirements will be tested for acceptance by the customer.
When assigning the priority weights for the requirements, keep in mind that a perceived importance of a feature does not mean that it should be given great attentiona and implemented the first. For example, user authentication carries a very high priority in any real system—it’s usually a must feature to have. However, in this course you will not get many points for showing that your system can correctly login the user and allow the user to register with the system, unless you invented a novel way for user authentication. In other words, user authentication is assumed as a required feature and there are millions of implementations on the Web that can be simply copied. Make sure that it is there and cite the source that you used to implement it, but do not waste the report pages on describing the mechanics of user authentication, which you probably simply copied from somewhere. (Of course, if there is something novel about how your system does user authentication, you should describe this novelty in your report.)
Therefore, you should assign the highest priority to the key functional features of your project. The supporting activities (such as login and user registration) should be simply implemented without thinking much what priority should be assigned to them. Always keep your focus on what matters the most, what is unique and novel about your project, so that you can demonstrate the most impressive and the most competitive project in the class!
In Section 2.b) Non-Functional Requirements, you must ensure that your requirements are testable. Some examples of good non-functional requirements for the restaurant automation project would be:
In Section 2.b) On-Screen Appearance Requirements, show what you received from your (imagined) customer—how
your customer thinks the user interface should look like. It will be mostly text, some pictures downloaded from the Web,
or even hand-drawn sketches.
Do not include polished screen shots that you already invested great effort to create. Based on these customer-generated requirements, you proceed to produce nicely polished user interface design and report nice screen shots in your Section 4 on user interface specification.
Again, Section 4 shows what you created in response to your customer’s request! You will not receive from your customer as a requirement a nicely designed screen shot of the required user interface. What you need to do is to imagine what your customer would provide—probably some text description and hand-drawn sketches. Then, in response to your customer requirements, you will proceed to create nice graphics and include them in Section 4 of your report.
The user effort should be minimized for all applications (Section 4.b). However, this issue is more important in some applications than in others. If you are developing a video game or biology labs, you should focus primarily on the visual appearance of your user interface. Estimating and minimizing the user effort is of secondary importance in such applications, and should be done later. (Of course, there are always exceptions—in some video games it’s important that you shoot them first…)
Section 5 Domain Analysis must include the description of how the domain model was derived. It should show the analysis process that you carried out to derive your domain model. Showing only the domain model diagram will yield very few points.
Section 7 References should list ALL sources that you used for your project. It is recommended that you list your references in the Harvard reference style. All team members must be involved in preparing this section, and provide a list of URL's, books, or other sources that they used for the project. If the section is missing or judged incomplete, up to 5 points will be deducted from the report grade.
It is not enough to report the final design choice that you selected—you should also discuss what alternatives you considered and what are your arguments for choosing your particular design. A lot of misunderstaning during the grading process can be avoided by discussing the alternatives and arguments in advance, instead of writing explanations upon inquiry.
There is no limit on the number of pages for the
report. Of course, you should avoid stuffing your report with
redundant or irrelevant material. The report must be
self-contained; the grader should not need any other
material to understand the report. You should provide as
much details as possible (particularly in the use case scenarios and
the domain model), but these are business details, i.e., how
the user typically interacts with the system to obtain the
service. You should not go into software details of
how you plan to build this system.
(The latter will be part of Report #2.)
Brevity is good because it will be easier for you to create a professionally looking technical report—it is easier to maintain consistency, clarity, and readability for shorter reports. Check also: 10+ ways to reduce wordiness in your writing (TechRepublic)—when you streamline your wording, your message becomes more powerful and clear.
Do not just show the UML diagrams—for all figures, tables, and diagrams provide some narrative discussion! Unfortunately, diagrams, particularly technical diagrams, are rarely if ever self-explanatory. You should document the alternative solutions that you considered as well as the arguments for the final choice. Diagrams only represent your final solution, but do not explain why you decided on this solutions and what alternatives were considered. Hence, all diagrams must be accompanied with explanation and discussion of alternatives and tradeoffs. Anything that could lead to ambiguity or misunderstanding on the reviewer’s part, should be clearly explained. Explanations should be written in prose and key arguments highlighted in bullet points. Use the terminology from the textbook and the lecture notes—this is important so to facilitate the report grading and reassure the grader that you are studying the textbook and you understand it.
Provide as much graphics as you can—not only UML diagrams, but any kind of diagrams and illustrations that will make it easier for us to understand and evaluate your effort. Graphics are always helpful, you have probably heard the saying “a picture is worth a thousand words”!
If you did some field work for your project, please include it as an Appendix to your report. For example, if you are working on parking garage automation, you might have visited a local garage operator and discussed the the problems they encounter and the viability of your project. If you are working on restaurant automation,
you might have conducted interviews with employees of local restaurants. If you are developing virtual biology labs, you might have interviewed biology students and faculty. Etc.
Include as much details of those discussion in the Appendix of your report. (Idealy the interviews should be transcribed, but this is not required.)
In your Customer Statement of Requirements, discuss how you incorporated this knowledge gleaned from your “customer” into the requirements for your system.
A typical beginner’s mistake is to try to do everything at once and accomplish nothing. Students identify twenty or more use cases and try to elaborate all of them. That would be impossible in the given time frame even for a very experienced developer! Your project will end up lacking focus and all use cases appear naive and simplistic.
I am not suggesting that you narrow the focus of your project entirely and scale down any ambitions. – No! Think of this report as having two parts:
Select two to three most important use cases that you will present for your first demo and provide detailed (“fully dressed”) description only for the selected use cases. Do them well and make them count! Refrain from documenting all the use cases in full detail. Even if you feel that you can elaborate all of your summary use cases, refrain from doing it! Such confidence usually signals that you don’t know much about your problem. Your use cases will be elaborated only superficially and none of them will pass a reality check—none of them would be able to perform an actual task in a real system.
Focus on few key features of your system and do them so that they are believable and realistic. Just leave your other use cases alone. You will achieve a firmer grasp on the purpose of the exercise if you focus intently on few features rather than haphazardly on many.
IMPORTANT: Keep in mind that there are two iterations of your project during this course. Don’t try to do everything in the first iteration—leave something for the second iteration!
After the first demo, you will select some of the remaining use cases and elaborate those for your second demo.
All teams must include in their reports a table showing effort breakdown. This activity has two purposes:
IMPORTANT NOTE: This report should contain only information about your requirements analysis, user interface specification, and domain modeling. You should not report any activities related to the writing the program code (i.e., system implementation).
Such activities should be reported as part of your first demo.
The team members who focused on implementation and contributed less to the preparation of this report should not ask that the individual contributions be artificially tweaked so that their efforts are properly reflected. Instead, they should claim greater contribution to the project demo.
IMPORTANT NOTE: The effort breakdown must reflect all activities that contributed to the particular component of the report. Such activities include the following:
The effort-breakdown table format for this report is as follows. Assume that the team has five members and, for the sake of illustration, their individual responsibilities are agreed to be as shown in this responsibility matrix:
|Note: See point allocations in the table below.|
|Member 1||Member 2||Member 3||Member 4||Member 5|
|70 %||20 %||10 %|
|Sec.1: Customer Statement of Requirements|
|50 %||50 %|
|Sec.2: System Requirements|
|Sec.3: Functional Requirements Specification|
|67 %||10 %||23 %|
|Sec.4: User Interface Specs|
|Sec.5: Domain Analysis|
|25 %||75 %|
|Sec.6: Plan of Work|
|50 %||50 %|
The values in each row must add up to 100 %. The values in each column will give us the responsibility levels for individual team members, as follows. If we multiply the percentages for individual team members with total number of points, we will know how many points each member can potentially earn. For instance, Member 1 in the above example can earn a maximum of:
From this chart we can easily see that the responsibility allocation in this example scenario is not well balanced across the team. Ideally, all members should take on approximately equal level of responsibility. Hence, in the above scenario, Members 1 and 3 should take on more responsibilities. As explained at the beginning of this section, “responsibility” includes all activities that contribute to the report writeup, not only the actual writing of the text and drawing the diagrams!
The report should be prepared electronically. It is mandatory to use a software tool for producing UML diagrams for this report. Hand-drawn UML diagrams are not acceptable. Read the supplementary textbook on UML for details on UML notation. Here are some options for software tools for UML diagramming. You may search the Web and find some other tool as well. Any tool that supports the UML symbols is acceptable.
Hand-drawn figures are acceptable for illustrating the user interface requirements. These figures must be drawn using black ink on white paper, scanned, and inserted as images in this document. It is your responsibility to ensure readability of your diagrams.
Additional information about report preparation is available here.
You should start implementing at least some functions of your
system immediately. Building prototypes and playing with them will help you to better specify
and design your system. You should not wait until after submitting Report #2 to start with coding—the first
demo is not that far away!
Check about the project resources here.
A note about mock up screens for the user
Keep in mind that you do not need to program in a programming language in order to start generating mock up screens for your system. The idea of mock up screens is that you generate them in PowerPoint or another graphics editor, not in a programming language.
However, do not report about the pilot implementations in this
report. The first time we expect you to report about the
implementation is in the first demo.
5. Report Grading
This report will be graded only after the entire report is submitted.
Individual parts of the report will not be graded immediately after the submission.
However, 50% of points will be deducted from the parts that were not submitted on time.
If time permits, we will provide feedback on the individual parts before the entire report is due.
The report grading consists of two steps:
All reports will be graded independently of each other, based on the following table. The table shows the maximum possible point score for each section. Your actual score may be
lower, depending on the quality of your work.
The actual points will be assigned based on the actual grading checklist.
|90   +   10 points for project management *up to 5 points will be deducted for missing or incomplete references|
IMPORTANT NOTE: Unfortunately, it is impossible to design the above table so that “one-size-fits-all-projects”. Therefore, consider this distribution as a generic starting point, that may be adapted to reflect the characteristics of a given project. Points may shift among sections if some components are deemed more important for a particular project. As stated at the beginning of this page, if the project needs only simple use cases but sophisticated algorithms, then Section 3 may be done perfectly, but will carry less than the maximum of 30 points. Instead, the points will be shifted to other sections that appear more critical for the given project, such as Section 4 on user interface or Section 5 on the domain model. If the Mathematical Model (Section 5.c) or description of algorithms is more important for your project than use cases or user interface, then the math model section may receive up to 15 points. Etc.
Each team member will be assigned score points, based on their declared contribution to the report. This is only the first step in determining the student grades. See details here.
5.2 Cross-Comparison of Reports
It is not enough only to meet the listed requirements to receive the maximum grade. For example, having a perfect report for a trivial project will result in a very low overall grade. Thus, the overall quality and functionality of the project is the key scaling factor for all other aspects of the grade. The reports will be compared as a whole relative to one another, and a holistic grade will be assigned.
The “holistic grade” part of the grade is hard to quantify; it is essentially how well your report compares to the others in the class. It assesses the overall impression about the envisioned product and your creativity and the progress you made so far. It also includes the general appearance of the report. The report that is judged as best will receive 100% as the holistic grade for this report. Of course, there may be several teams with an impressive report, so several teams may receive the maximum holistic grade.
These are key ingredients of a competitive report:
Your report should appear to an outsider as if it was written by a single person. Of course, each team member will contribute different parts of the report, but everyone should read the entire report and ensure clarity and integrity, that it uses consistent terminology and that diagrams in different sections are consistent with one another. The whole report should use the same writing style, language, etc., so that it appears as if it was written by a single person.
Do not write your report as a collection of hints that only you know how to decode. Write your report from a third person’s point of view. You know everything about your project so you do not need much information to understand what is in. A third person has only general knowledge of software engineering and needs help in understanding how general principles are applied in your specific context.
After this step, the student grades will be calculated as detailed here.
We will not assign letter grades for individual deliverables.
The way this report grade will become part of the final grade
is explained here.
Report #1 contributes up to 10% of the final grade. The maximum possible grade on Report #1 is 100. Therefore, a student who earned 100 on report #1 will receive 10 points towards his or her final grade. A student who earned 50 on report #1 will receive 5 points towards their final grade. And so forth.
You must ensure that your report is complete and that your graphics are readable (especially if you are including hand-drawn sketches). We will not check this for you and ask you to resubmit. If we find that the diagrams are not legible, we will consider them missing. Follow-up submissions of report sections that were prepared but omitted by mistake will not be accepted.
When submitting Part 1, the document must include the following sections:
When submitting Part 2, the document must include the following sections:
The full report must contain all sections specified in the Report Format (previously submitted sections may be revised as needed).
Each team should email their report (single PDF document only!!!) both to the instructor and the TA on or before the due date.
The report should also be posted for download on your project website (for free web hosting, see here).
All teams are required to meet the deadline, as well as to follow the instructions about the format of submission, because it creates a logistic nightmare when all students follow different deadlines and document formats.
Submission deadline is usually by end of the day on the due date.
Back to the course home pageIvan Marsic