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).       Also see the successive  Report #2:  SYSTEM DESIGN.

  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.

In each section of all of your report, always make clear the separation between your sub-projects:

The report sections are as follows:

Part 1:

  1. Customer Problem Statement
    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 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.
    2. Decomposition into Sub-problems
      Based on the problem statement, specify how you decomposed the overall problem into sub-problems.
    3. 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).
    1. Business Goals
      Structure the goals hierarchically;  show them in a diagram, so that the relationship between the goals and sub-goals is clear.
    2. 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.
    3. Enumerated Nonfunctional Requirements
      List, prioritize, and describe the FURPS+ requirements. The non-functional requirements numbering should continue the functional requirements list.
    4. 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)
Part 2:
  1. 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.
    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 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.
    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. System Architecture
    1. Identifying Subsystems
      Draw and describe UML package diagram of subsystems in your system (See the UML textbook)
    2. Architecture Styles
      Describe the architectural styles used in your design   (Google search software architectural styles example)
    3. 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?
    4. 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.).
    5. 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?
    6. 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.

  2. 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.
  3. 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.
  4. 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:

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:

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

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

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

Back to the course home page

Ivan Marsic
Wed Jan 23 12:23:21 EST 2019