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

Here are some general considerations when designing, proposing and evalulating API's.

Overall Process:

DOCUMENT, DOCUMENT, DOCUMENT!

Organize Working Sub-groups

1. Elect one of the HW teams to be the group leaders.   
   1. Record the group leader team name and members in the wiki.
   2.  The group leader team's 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.
2. Elect one of the HW teams to be the Documentation maintainers.  -- This is the most important role in the group!
   1. Record the Documentation maintainer team name and members in the wiki.
   2. The documentation maintainer team's responsibilities include:
• Ensures that all documentation is organized and easily accessible by all.
• Ensure that all documentation is complete -- note that each subgroup should be writing up their own documentation!  This includes but is not limited to
  • Subtask allocations to each HW team in the group
  • Any notes and discussions e.g. research and decision notes.
  • All diagrams, e.g. UML use case and class diagrams.
  • All design rationales
  • The formal design proposal document  -- keep this separe
  • Any oral presentation materials, e.g. slide decks, etc.
• The documentation maintainers' job is to organize the information, not write it!   Each team that is working on a specific area is responsible for writing their own documentation!
3. Elect other HW teams to fill the remaining roles, e.g.
   1. Presentation organizers -- responsible for organizing and written and oral presentation materials, including ensuring that a coherent, relevant message is being presented.
   2. Repository maintainers - responsible for maintaining and organizing the group's shared repository
   3. Testing coordinators -- Responsible for coordinating the testing activities to ensure proof-of-viability of the group's design and for coverage of use cases.    A design proposal is not viable if it is untested!
4. Assign design, coding and testing tasks to the HW teams 
   1. All task assignments will be by HW assignment teams (pairs/triplets).   HW teams should not be broken up.
   2. Record the task descriptions and task assignments in the wiki
   3. Record the results of the task 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

Often the course will evalute the participants' performance in the design process.  Typical criteria include but are not limited to:

• Team leaders:  overall completeness and cohesiveness of the proposed API  
• Sub-groups: clarity and completeness of the documentation pertaining to their assigned API section including the wiki and diagrams 
• Everyone:  Voting participation 
• There will be multiple design activities in the course.
• Design activity evaluation will typically 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