Software Engineering Project Report
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).
Report #2: SYSTEM DESIGN.
Also see the successive
1. Report Format
2. Report Preparation
3. When to Start Coding
4. Report Grading
5. Report Submission
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.
1. Purpose
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.
2. Report Format
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.
Cover Page and Individual Contributions Breakdown, as specified here.
The contributions breakdown must contain the responsibility matrix and responsibility allocation chart as
described in Section 2 below.
Even if all team members contributed equally, this must be explicitly stated on the Contributions Breakdown
page.
Table of Contents
Check that the section headings and numbers, and page numbers listed here are correct.
Work Assignment
Show how you divided your team into 3 or 4 sub-teams and list the individual student competences
In each section of all of your report, always make clear the separation between your subprojects:
All requirements must be listed separately for each sub-project; do NOT combine the
requirements together into a single list
All use cases must be shown separately for each sub-project
All user interface designs must be shown separately for each sub-project
Etc.
The report sections are as follows:
Part 1:
1. Customer Problem Statement
a. Problem Statement
A minimum 3-page high-level narrative about your project. The narrative should not be written from
the developer’s perspective, describing the features of the planned system.
Rather, put yourself into a customer’s role, and write your problem statement as if your imagined
customer would write it! —Describe the problem that your customer is facing and his or her
suggestions about how a software system could help.
Your problem statement should be based on your project proposal, revised and improved as necessary.
If you’re working on an existing project idea, then summarize and rephrase the description given
therein.
You are welcome to borrow anything and everything from the past student projects posted there; just
make sure that you describe explicitly how novel or different your extensions will be compared to the
past projects.
b. Decomposition into Sub-problems
Based on the problem statement, specify how you decomposed the overall problem into sub-problems.
c. Glossary of Terms
List important terms and their definitions to ensure consistency and avoid ambiguity in the system
specification. Use the language of the application domain and avoid uncommon terms or define these as
well.
It is helpful to illustrate the complex terms by providing images and graphics to help reader’s
understanding (find images on the web).
Do not define the general computing terms, such as “network protocol,” “client/server,” “thread,” “user
interface,” etc. Define only the new terms that you are introducing for your system, or common words
that have special meaning in the context of your system.
2. Goals, Requirements, and Analysis
Note: Instead of system requirements, you may wish to write User Stories (write one or the other, but not
both).
a. Business Goals
Structure the goals hierarchically; show them in a diagram, so that the relationship between the goals
and sub-goals is clear.
b. Enumerated Functional Requirements
Extract the requirements from the customer’s narrative and list them in a table, one row per
requirement. The first column shows a unique label “REQ-x”. The second column shows an assigned
Priority Weight of this requirement. The third column briefly describes the requirement.
c. Enumerated Nonfunctional Requirements
List, prioritize, and describe the FURPS+ requirements. The non-functional requirements numbering
should continue the functional requirements list.
d. User Interface Requirements
For projects that are heavy on graphics (such as virtual labs or a video game) the user interface makes
up the majority of the requirements. Again list, prioritize, and describe the user interface requirements,
but also include a graphic illustrating each requirement. You may find images on the Web or make
hand-drawn sketches on paper, then scan them and insert as images into your report.
Do not spend time polishing these graphics, because polishing is part of Section 4 User Interface
Specification (below)
Project Management (described in Section 7 below) and References (described in
Section 8 below)
Part 2:
3. Use Cases
Derive the use cases based on the requirements from Section 1 and Section 2 above.
Note: If you wrote user stories instead of system requirements, you still need to write use cases. This fact is
implicitly recognized by the introduction of “epics”. If you like epics, write epics.
a. Stakeholders
Identify anyone and everyone who has interest in this system (users, managers, sponsors, etc.).
Stakeholders should be humans or human organizations.
b. Actors and Goals
Identify the roles of people or devices that will directly interact with the system, their types (initiating
vs. participating) and the goals of the initiating actors.
c. Use Cases
i. Casual Description
For all use cases that you can think of (based on your System Requirements), write a brief or
casual text description. List explicitly the requirements that each use case responds to.
ii. Use Case Diagram
Draw the use case diagram with all the use cases. Indicate the relationships, such as <<include>>
and <<extend>>.
iii. Traceability Matrix
Show how your system requirements map to your use cases. Calculate the priority weights of
your use cases. The use cases with the highest priority should be elaborated and planned for the
first demo.
iv. Fully-Dressed Description
Select a few most important use cases and provide detailed (“fully dressed”) description. The
“most important” use cases are indicated by your traceability matrix.
Your event flows must show step-by-step every action that the initiating actor (“user”) can take
while running the given use case.
d. System Sequence Diagrams
Draw the system sequence diagrams for the few most important use cases selected above.
4. User Interface Specification
(Note: If your system prints some forms or generates periodic reports, this is also considered part of the user
interface and the format of forms/reports must be specified in this section.)
The user interface should be specified only for the use cases elaborated in the previous section (“fully dressed”
use cases).
a. Preliminary Design
For a given use case, show step-by-step how the user enters information and how the results appear on
the display.
Use display mock-ups and describe exactly what fields the user enters and buttons the user presses.
Describe navigational paths that the user will follow.
In case you are developing a graphics-heavy application, such as a video game, this is one of the most
important sections of your report.
b. User Effort Estimation
Select several typical usage scenarios and, as you walk through the flow of events, count and report the
number of mouse clicks and/or keystrokes that are needed to accomplish the task. What fraction of
these goes to user-interface navigation vs. clerical data entry?
See example in Appendix A: User Effort Estimation.
Project Management (described in Section 7 below) and References (described in
Section 8 below)
Part 3:
5. System Architecture
a. Identifying Subsystems
Draw and describe UML package diagram of subsystems in your system (See the UML textbook)
b. Architecture Styles
Describe the architectural styles used in your design (Google search software architectural styles
example)
c. Mapping Subsystems to Hardware
Does you system need to run on multiple computers? For example, you may have a client (web
browser) and a server (web server) subsystems, running on different machines.
If NO, skip to the next item;
If YES, what subsystems run on which machine?
d. Connectors and Network Protocols
If your system runs on a single machine, this item probably does NOT apply; skip to the next item;
Otherwise, which communication protocol do you use, e.g., plain Java sockets, Java RMI, Java JDBC,
HTTP, etc. Explain why you made your specific choice.
If you are using plain sockets, attach the description of the communication protocol (types of messages,
message format, etc.).
e. Global Control Flow
Execution orderness: Is your system procedure-driven and executes in a “linear” fashion, where
every user every time has to go through the same steps, or is it an event-driven system that waits
in a loop for events, and every user can generate the actions in a different order?
Time dependency: Is there any timers in your system?
Is your system of event-response type, with no concern for real time, or is it a real-time system? If
it is real-time, is it periodic, and what are the time constraints for each period?
f. Hardware Requirements
What system does resources your system depend upon? Examples are, screen display, disk storage,
communication network, or you may be accessing some special sensor/instrument.
Describe exact requirements for these resources in order for your system to run. For example, you need
color display, with minimum resolution of 640 × 480 pixels; minimum of 2 Gbytes hard disk space;
minimum network bandwidth 56 Kbps.
6. Project size estimation based on use case points.
For Report #1, estimate the size of your project in terms of use case points only for the use cases elaborated in
this report.
7. Plan of Work
Describe what your group is planning to do after submitting report#1 until the end of the semester. Show the
roadmap with projected milestones and dates by which you plan to accomplish them. Of course, your plans
for the short term (next few weeks) should be much more detailed than further in the future.
Preferably, you should use Gantt charts for planning and scheduling your project (also check: Gantt chart
basics: What it is, benefits, & alternatives). (Rutgers students can download Microsoft Project at the University
Software Portal.) Consider also creating your product roadmap.
Include the product ownership description from your project proposal, and provide the breakdown of
responsibilities: what each team member did so far, is currently doing, will do in the future, including
management and coordination activities.
8. References
The list of references should contain exact references and URLs of any material that is used in the project and
doesn’t come from the textbook. If a reference is listed but not cited/mentioned in the main text, explain
briefly in what way it was used.
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:
“The cook’s user interface should allow viewing the next food order using less than 5
screen touches, starting from the root window.”
“The cook’s user interface should allow notifying the waiter that food is ready using less
than 3 screen touches, starting from the root window.”
“The hostess’s program should be so reliable that it does not crash more than once a
month.”
“The cook’s user interface should show text and graphics so that it is readable by a person
with average eyesight from a distance of 1 meter.”
Notice the quantitative values in the requirements, which ensure that the requirements can be
tested when the software is implemented.
The actual numbers are just examples, and it is your duty to decide what the reasonable values
are. You may even list some unrealistic requirements from your customer (e.g., asking that the
cook can notify the waiter that the food is ready with a single touch of the screen), and then
when you do analysis of the user interface (Section 4 of your report), then you demonstrate in
your analysis that the customer’s demands were not realistic!
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.
2.1 Best way to achieve nothing is to try and do everything
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:
“visionary” part that consists of everything before Fully-Dressed Description of Use Cases:
customer problem statement, system requirements, and casual description of use cases
“practical” part that starts with Fully-Dressed Description of Use Cases and contains all the
remaining sections
In the “visionary” part of your report, you should try to be as ambitious as you can. Describe
all possible features and extensions that you can think of.
Then, in the “practical” part of your report, you should be practical (!) and start with a narrow
focus. Here is what you will actually do from all the options that you invented.
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.
2.2 See Also
The above list gives only the main required items for this project report. It is absolutely
necessary that you read and understand the relevant materials in the class lecture notes in
order to be able to prepare a good project report. Check also Requirements analysis @
Wikipedia.
Also, IEEE Recommended Practice for Software Requirements Specifications contains (in the
appendix) several sample outlines for the description of specific requirements: IEEE Std 8301993 (Superseded by IEEE Std 828-1998).
Check also the new IEEE Recommended Practice for Software Requirements Specifications: IEEE
Std 830-1998 (Revision of IEEE Std 830-1993)
3. Report Preparation
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-andwhite/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.
4. When to Start Coding
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:
1. Grading the reports
2. Assigning individual student grades based on the report grades
Each step is detailed next. See also the grading policy for the assigning the overall team grade
vs. grades for individual students.
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.
6. Report Submission
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. Followup 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:
Cover Page and Individual Contributions Breakdown
Table of Contents
Section 1: Customer Problem Statement
Section 2: System Requirements
Project Management
References
When submitting Part 2, the document must include the following sections:
Cover Page and Individual Contributions Breakdown
Table of Contents
Section 1: Customer Problem Statement — revised as needed
Section 2: System Requirements — revised as needed
Section 3: Use Cases
Section 4: User Interface Specification
Project Management
References
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.
Back to the course home page
Ivan Marsic
Wed Jan 23 12:23:21 EST 2019