Back to the course
home page
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 Problem Statement and Section 2 Goals, Requirements, and Analysis)
2.
Part 2 (Section 3 Use Cases 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.
The purpose of project reports is to communicate the design ideas and
implementation choices to other stakeholders; the purpose is not to
“write documentation.”
In case of student projects, the communication is primarilly to the instructor and graders.
Without effective communication, it is not possible to evaluate the originality, quality,
and the extent of the work.
Therefore, during the report writing, ask yourself: “Am I effectively communicating
the key ideas and important aspects of my work?”
and do not bother with “writing documentation.”
Focus on substance, not on formalities. The most important thing is that your project is
novel, creative, professionally executed, and clearly communicated. Do not focus on counting
the number of use cases or the number of pages of your report.
Ask yourself: are we developing great software?
Does this report clearly explain our work and our contribution, so that graders
can understand and appreciate it?
Try to avoid typical mistakes that contribute
“communication noise” and impair or prevent effective communcation.
Note that the following generic format may not fit well all types of projects.
Different projects will require different distribution of effort for Section 3
Functional Requirements Specification
versus Section 4 User Interface Specification.
All projects require both sections, but their relative representation 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 virtual 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.
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.
The report sections are as follows:
Part 1:
A minimum 3-page customer problem statement is required (Section 1.a). Your problem statement 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 Problem Statement 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 display 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 problem statements 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 Problem Statement (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 can be tested. Some examples of good non-functional requirements for the restaurant automation project would be:
In Section 2.b) User Interface 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.
In Section 3 in particular, but throughout the report as well, avoid repetition because repetition is boring. If one detailed use case looks very similar to an already-presented use case, omit it from the report. For example, a new use case would have almost identical schema, but with few minor changes, such as use case name or few other names in the schema. You need to briefly list the detailed use cases that you omitted and say which of the presented use cases are similar to the omitted ones. Repetitive use cases may be needed in real-world problems (although I doubt it), but repetition is useless and uninstructive for the purposes of this course.
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 virtual 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 8 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.
Although the number of pages for the report is not limited, more concise reports are easier
to understand and evaluate. The report must be self-contained; the grader should not need
any other material to understand and evaluate the project. In the use case scenarios, provide business details, i.e., how
the user typically interacts with the system to obtain the
service. At this stage, avoid the details of your planned software, which will be addressed
in 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”!
You are welcome to use any symbol notation (UML is not required),
as long as you define the meaning of your symbols. The advantage of using UML is that
the symbols are already well defined and there are many sources where the definitions
can be looked up.
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 labs, you might have interviewed 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 Problem Statement, 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.
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.
Consistency, clarity, and correctness of the report are
critical. The report must be complete, in the sense that it is
self-contained and the reader doesn’t need other
materials to understand it. Anticipate what could be confusing to the
graders and clarify every possible source of ambiguity or
inconsistency. Make sure that all team members carefully read the
entire report and understand its contents completely and
clearly.
The report should appear to any reader 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.
The report should have professional appearance; make sure that it is neat, easy to read and understand, with clearly labeled section headings, figure captions, pagination, and without grammatical and typographical errors. Also, check that diagrams and images are readable when printed (i.e., letters or symbols are not too small and illegible). If you are using colors in images and diagrams, check that they are discernable when printed in black-and-white/grayscale. Every figure/table must be referenced in the text and properly described.
Do not write your report as a collection of hints for which only you know the actual meaning. 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.
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
interface.
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 grading checklist.
The maximum possible point score for each report is 100 points. The actual score may be
lower, depending on the quality of different elements of each report.
Each team member will be assigned points, based on their declared contribution to the report, 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.
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 (the sections previously submitted within partial reports may be revised as needed).
Each team should submit their report (single PDF document for each team!!!)
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 by midnight on the due date.