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 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.

  1. Report Format
  2. Effort Breakdown
  3. Report Preparation
  4. When to Start Coding
  5. Report Grading
  6. 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.   Report Format

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.

Part 1:
  1. Customer Statement of Requirements (CSR)
    1. 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 CSR 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 CSR 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.
    2. 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).
      Another option is to provide web links where to find more complete definitions of your terms.
  2. System Requirements
    Note:  Instead of system requirements, you may wish to write User Stories (write one or the other, but not both).
    1. 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.
    2. Enumerated Nonfunctional Requirements
      List, prioritize, and describe the FURPS+ requirements   (also check Concepts: Requirements). The non-functional requirements numbering should continue the functional requirements list.
    3. On-Screen Appearance Requirements
      For projects that are heavy on graphics (such as biology labs or a video game) the on-screen appearance makes up the majority of the requirements. Again list, prioritize, and describe the on-screen appearance requirements, but also include a graphic illustrating the 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)
Part 2:
  1. Functional Requirements Specification
    Derive the use cases based on the requirements from Section 1 and Section 2 above.
    1. Stakeholders
      Identify anyone and everyone who has interest in this system (users, managers, sponsors, etc.). Stakeholders should be humans or human organizations.
    2. 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.
    3. Use Cases
      1. 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.
      2. Use Case Diagram
        Draw the use case diagram with all the use cases. Indicate the relationships, such as <<include>> and <<extend>>.
      3. 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.
      4. 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.
    4. System Sequence Diagrams
      Draw the system sequence diagrams for the few most important use cases selected above.
  2. 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).
    1. Preliminary Design
      For a given use case, show step-by-step how the user enters information and how the results appear on the screen.
      Use screen 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.
    2. 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.
Part 3:
  1. Domain Analysis
    1. Domain Model
      Show the process of deriving the domain model and then draw the diagram. Provide text description of:
      1. Concept definitions
      2. Association definitions
      3. Attribute definitions
      4. Traceability matrix — show how your use cases map to your domain concepts.
    2. System Operation Contracts
      Should be provided only for the operations of the fully-dressed use cases elaborated in Section 3.c), for their system operations identified in Section 3.d).
    3. Mathematical Model
      Do you use any mathematical models? E.g., you may use a statistical model for stock price prediction, or a geometric model for computing the trajectories for animate figures in a video game.
      If NO, skip to the next item;
      If YES, describe precisely your model.
  2. 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. (Rutgers students can download Microsoft Project at the University Software Portal.)
    Also 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.
  3. 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 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:

Notice the quantitative values in the requirements, which ensure that the requirements can be tested once 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), or the domain analysis (Section 5), then you demonstrate in your analysis that the customer’s demands were not realistic!

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.

1.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:

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.

1.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 830-1993 (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)   [ Get a copy here ].

2.   Effort Breakdown

All teams must include in their reports a table showing effort breakdown. This activity has two purposes:

  1. Help team members distribute the project responsibilities equitably
  2. Help instructor grade individual contributions fairly

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:

In other words, it is not only the person who did the writing of text for a section that should take the entire credit for this section. Everyone else who contributed and made it possible to do the actual writing should claim some credit.

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.
Team Member Name
Member 1Member 2Member 3Member 4Member 5
Res
pon
sibi
lity

lev
els
Project management
(10 points)
70 % 20 % 10 %
Sec.1: Customer Statement of Requirements
(9 points)
50 %  50 % 
Sec.2: System Requirements
(6 points)
 100 %   
Sec.3: Functional Requirements Specification
(30 points)
 67 %10 %23 % 
Sec.4: User Interface Specs
(15 points)
    100 %
Sec.5: Domain Analysis
(25points)
  25 %75 % 
Sec.6: Plan of Work
(5 points)
50 %   50 %
Note: You may wish to have additional rows in the responsibility matrix for all sub-sections of the report, particularly for sections that carry most points. This will give you more accurate view of responsibility allocation.

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:

0.7 × 10 points + 0.5 × 9 points + 0.5 × 5 points = 14 points
By repeating the same calculation for all team members, we will obtain the following chart of responsibility allocation across the team:
( Member 2: 1.0 × 6 + 0.67 × 30 = 26.1 points
  Member 3: 0.2 × 10 + 0.1 × 30 + 0.25 × 25 = 11.25 points
  Member 4: 0.5 × 9 + 0.23 × 30 + 0.75 × 25 = 30.15 points
  Member 5: 0.1 × 10 + 1.0 × 15 + 0.5 × 5 = 18.5 points )
responsibility allocation
chart

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!

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.

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. Individual report grading
  2. Cross-comparison of reports
Each step is detailed next. See also the grading policy for the assigning the overall team grade vs. grades for individual students.

5.1   Individual Report Grading

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.

Section Cust.stat.rq.
System Req'ts
Funct. Requirements Specs
User i'face
Domain Model
Plan
of
wrk
Ref's
Prob.
statm.
Glos
sary
Funct.
req'ts
Nonfct.
req'ts
FURPS+
UI
req'ts
Stkhld.
Actors
Goals
Use c.
casual
descr.
Use
case
diag
Use c
full
descr.
Sys.
seq.
diag
Prelm
design
Effort
estim
Conc
epts
AssocAttrib Cont
racts
Points 5 4 2 2 2 2 8 5 10 5 11 4 10 5 5 5 5 (-5)
Total
points
     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.

5.3   How does the Assigned Grade Translate to the Letter Grade?

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.

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. 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 page

Ivan Marsic
Mon Feb 13 21:01:56 EST 2012