Software Engineering

Report #1: SYSTEM SPECIFICATION — Iteration 1(a) —  (due date given here)

Note: Keep this report for future reference since it will become part of the final report (Report #3). Thus, as you progress through the semester, take every opportunity to revise, update and/or correct it.

1.   Report Format

The report must contain the following section. Each section should be clearly delineated, with its own heading and pagination. The sections should be numbered as below, to facilitate the grading process.

1. 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
2. Table of Contents
   Make sure that the page numbers listed here are correct
3. Customer Statement of Requirements
   A minimum 3-page high-level narrative about the project (see below).
   This could be copied from your project proposal, revised and improved as necessary, OR
   If you’re working on one of the projects given in Section 1.5 of class lecture notes, then summarize and rephrase the description given therein.
   Enumerate all the requirements at the end of this section.
4. 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.
5. Functional Requirements Specification
   1. Stakeholders
      Identify anyone and everyone who has interest in this system (users, managers, sponsors, etc.).
   2. Actors and Goals
      Identify who 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 plan to have in the final product, write a brief or casual text description.
      2. Fully-Dressed Description
         Select a few most important use cases (those that you plan to have implemented by the time of the first demo) and provide fully dressed description.
      3. Use Case Diagram
         Draw the use case diagram with all the use cases.
      4. System Requirements - Use Case Traceability Matrix
         (search the Web)
   4. System Sequence Diagrams
      Draw the system sequence diagrams for the few most important use cases selected above
6. Nonfunctional Requirements
   List and describe the FURPS+ requirements   (also check Concepts: Requirements).
7. Domain Analysis
   1. Domain Model
      Draw the domain model and provide three tables with:
      1. Concept definitions
      2. Association definitions
      3. Attribute definitions
   2. System Operation Contracts
      Should be provided only for the operations of the few use cases elaborated above.
   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 game.
      If NO, skip to the next item;
      If YES, describe precisely your model.
8. User Interface Design
   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.
   1. Preliminary Design
      Describe navigational paths that user will follow when interacting with the system. Show the screen mock-ups that the user will see and what parameters they’ll need to enter.
   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 here (Appendix A)
9. Plan of Work
   Describe what your group is planning to do after submitting report#1 until the end of the semester. List the projected milestones and dates by which you plan to accomplish them. Of course, your plans for the next few weeks should be much more detailed than for the April/May period.
   Preferably, you should use Gantt charts for planning and scheduling your project. (Rutgers students can download Microsoft Project at the University Software Portal.)
   Also provide the breakdown of responsibilities: what each team member did so far, is currently doing, will do in the future.
10. 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. Each reference should be cited in the main text; otherwise, it should not appear in the list of references.

A minimum 3-page customer statement of requirements is required, see item #3 above. This should describe informally, without the use-case jargon, 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 gets deployed). Use the application domain 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 are given in Section 1.5 of class lecture notes.
Enumerate all the requirements at the end of this section. Each requirement should briefly state what the user should be able to do using the system or what the system should do automatically, e.g., at periodic intervals.

Also see Appendix A: User Effort Estimation

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 to read any other material to read and 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—provide some narrative! 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.

The phrase “few-most-important-use-cases” used above is not meant to discourage you from documenting all the use cases in full detail. If you have enough time to do it all—go for it! But, be carefull not to get overextended and end up not being able to meet the deadline. Remember, in the spirit of agile methods: Do the best you can in the time available and hand in your report on time.

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)

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

The values in each row must add up to 100 %. The values in each column will give us the responsibility levels for individual team members, as follows. If we multiply the percentages for individual team members with total number of points, we will know how many points each member can potentially earn. For instance, Member 1 in the above example can earn a maximum of:

From this chart, we can easily see that the responsibility allocation in the example scenario is not well balanced across the team members. Ideally, all members should take on approximately equal level of responsibility. Hence, in the above scenario, Members 1 and 3 should take on greater responsibility levels and Members 2 and 4 should reduce their responsibility levels.

The report should be prepared on computer (special negative points for handwriting and hand-drawn figures). Using a software tool is mandatory for producing this report. Hand-drawn diagrams are not acceptable. Read the supplementary textbook ( Miles & Hamilton: Learning UML 2.0 ) for details on UML notation. Here are some options for software tools that support UML design:

• Omondo EclipseUML http://www.omondo.com/ (Academic License available for free)
  works with Eclipse http://www.eclipse.org/
  Note: This tool is also installed in EIT Lab (D-110)
• ArgoUML http://argouml.tigris.org/
  see also ArgoUML @ Wikipedia.
• Rational Rose http://www.rational.com/tryit/index.jsp
• http://www.microgold.com/

4.   When To Start Coding

You should start implementing at least some functions of your system immediately. This code 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 departmental 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.   Grading

See also the grading policy for the assigning the overall team grade vs. grades for the individual members.

The reports will be graded as follows:
(NOTE: Check also the actual grading sheet.)

IMPORTANT NOTE: 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 “extra effort” part of the grade is hard to quantify; it is essentially what you do more than the minimum required above—how far you go “beyond the call of duty.” It also includes the general appearance of the report and the overall impression about the envisioned product and your creativity and current progress. Some indications of how extra points will be assigned are given in the actual grading sheet. You should demonstrate extra effort to receive 100% the total score for this report.

These are key ingredients of a successful report:

• Your project should appear as sufficiently ambitious for a semester of work by a team of soon-to-graduate engineering students. It should not leave impression that this can be done by a single person, or within a much shorter time.
  • Don’t worry if you don’t have many actors or many use cases. The complexity of the project is judged as a whole, not only by the number of actors and/or use cases.
• The report should demonstrate your creativity, knowledge, and skill in identifying and solving technical problems.
• 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 reviewers 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 have professional appearance; make sure that it is neat, easy to read and understand, with clearly labeled section headings, figure captions, pagination, and without gramatical and typographical errors. Also, check that diagrams and images are readable when printed (i.e., letters or symbols are not to 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.

6.   Report Submission

Each team should submit only one report to the TA. Email a PDF document of the report both to the instructor and the TA on or before the due date. Also, the report should be posted for download on your project website.

Submission deadline: 5:00 p.m. on the due date.

Back to the course home page