COMP 310 Spring 2017	Design Process Overall Guidelines

Design is a collaborative group process involving the inputs from many viewpoints, the weighing of pros and cons of all those viewpoints and the construction of a agreed-upon compromise that balances those concerns.

The following is a description of the overall structure and process in which class-wide design activities will be performed in the course.   There will be multiple design activities that are run, so this design process will be repeated each time.

The class will be divided into several large groups that will each work out a version of the inter-computer application programming interface ("API") that will govern the communications between connected computers.   Each large group will be further divided in to subgroups that will tackle specific areas of the API.

In this course, the design process will be evaluated in terms of participation in the process, NOT on the "correctness" of the solution.

Overall Process:

DOCUMENT, DOCUMENT, DOCUMENT!

Organize Working Sub-groups

1. Elect one of the HW teams to be the group leader.   The group leader team is not required to perform other tasks.
   1. Record the group leader team name in the wiki.
   2.  The group leader responsibilities include:
      • Make sure that all aspects of the API are covered
      • Identify where the APIs proposed by the subgroups are incompatible with each other
      • Ensure that all sub-groups have completed their tasks.
      • Ensure that all documentation is complete -- note that each subgroup should be writing up their own documentation!  
2. Create subgroups from the remaining members.   The number of subgroups should equal the number of API design tasks.
   1. All sub-group assignments will be by HW assignment teams (pairs/triplets).   The HW teams should not be broken up.
   2. Assign API design tasks to each subgroup
   3. Record in task assignments in the wiki

  Design Process

1. For each sub-group:
   1. Create Use Cases
      1. On the wiki, write down as many scenarios as possible that involve the assigned API section
         • Include both success and failure scenarios
         • Record all questions, concerns and ideas as they come up.  
         • Restrict your scenarios to just the assigned API section!  
           • Simply assume that the rest of the API processes exist and work.
           • If necessary, clearly state any assumptions being made about the state of the system or available data with respect to the rest of the API.   Resist the urge to work in tandem with the other subgroups!   Differences will be worked out later!    (Team leaders note: record any differences you see so that they can be addressed later.)
      2. Use Creately to generate a Use Case diagram for just the assigned part of the API section. Link to the diagram from the wiki.
         • Break the use cases down into as fine detail as possible.
         • Focus on actions, not method calls.
         • Remember that an arrow in a Use Case diagram means that one use case is composed of other use cases, not that one use case follows the other!
           • Number the arrows if necessary to indicate a temporal order in the composition of use cases.
      3. DO NOT CREATE CLASSES OR METHODS AT THIS STAGE!!
   2. Identify data elements being transferred in use cases
      • Address given questions regarding particular data types (see wiki).   Document group conclusions!
      • Just the data that is actually transferred from one computer to another
      • Focus on flexibility and extensibility
   3. Identify interfaces, classes and methods corresponding to use cases
      • Address given questions regarding particular entities (see wiki).  Document group conclusions!
      • Just the interfaces and classes that need to be common across computers
      • Focus on flexibility and extensibility
2. Presentation of API proposals by groups
   1. Team leader to give overall picture and goals of proposed API ONLY.
   2. Individual parts of API to be described by members of assigned subgroup
3. Class discussion
   • Pros and cons of each proposal
   • Non-binding voting on issues to get feel for consensus
4. Reformulation of API proposals by each group
   • Team leaders coordinate subgroups to make modifications to the API
   • Sub-groups responsible for designing the actual changes and updating documentation and diagrams
   • Remember that the final vote will be for one of the proposals, not a compromise, so build in the compromises that will enable your proposal to win.
5. Presentation of reformulated proposals by groups
   1. Team leader to describe high level view of changes that where made.
   2. Individual parts of API to be presented by members of assigned subgroup that did not present previously
      • Detail exactly what and why changes where made
6. Class discussion
   • Last attempt by groups to sway class to vote for their proposal.
   • Voting on adopted API

Design Tips

• Recording the questions is as important as recording the solutions!   A solution means nothing if the question it solves is not well understood.
  • Write EVERYTHING down!
• Vagueness kills. Be clear, concise and complete!
  • The clearer the statement of the problem, the easier the solution will come.
  • The clearer the statement of the solution , the easier it will be to convince others that it is the best solution.
• When editing the wiki, do quickly open the page for editing, make your changes and then close the editor.   Do not leave the page open for editing for long periods of time.    This will help minimize conflicts from multiple people editing the same page at the same time.

Evaluation

• Team leaders:  overall completeness and cohesiveness of the proposed API   (10 pts per design activity)
• Sub-groups: clarity and completeness of the documentation pertaining to their assigned API section including the wiki and diagrams  (10 pts per design activity)
• Everyone:  Voting participation  (1 pt per poll)
• There will be at least two design activities in the course.
• Design activity evaluation will comprise approximately 10% of the overall course grade (subject to change).

"Completeness" includes and is not limited to documentation of all issues, scenarios, use cases, protocols and interface/class/method definitions.

© 2017 by Stephen Wong