Milestone 1 Report - bounswe/bounswe2023group9 GitHub Wiki

Introduction

Welcome to milestone 1 report of bounswe2023group9! We are a group of enthusiastic students of CmpE352 Introduction to Software Engineering course, committed to designing and implementing a collaborative science platform that facilitates sharing, discussing and co-creating scientific knowledge. Our team members that have contributed to the project:

Table of Contents

1. Executive Summary

1.1 Project Description

Our project is a collaborative science platform that aims to transform the way scientific research is conducted by providing a structured and collaborative approach to developing knowledge in any scientific domain. The platform will be designed to reflect the natural organization of scientific knowledge, which is arranged in a directed acyclic graph, with each discovery building on previous ones. This project aims to facilitate the collaboration of scientists across different fields and geographic locations by providing a reliable platform to share data and findings. In addition, our platform will enable users who are enthusiasts of science to follow and engage with current research topics.

Our platform contains nodes that represent specific scientific theorems that are supported by proofs. Nodes can be connected with other nodes that are cited by edges. This allows for the creation of network graphs that visualize the relationship between different theorems. As a feature of the platform scientists can create workspaces to share their data and findings and collaborate with other scientists by working on the same workspace. These workspaces finalized by scientists can be published as nodes on the platform, after being reviewed and approved by reviewers.

Furthermore, the platform allows registered users to ask questions about nodes on the platform and receive answers from the contributors of the node. The platform also provides search functionality that enables users to find nodes and scientists related to the topics of their interests. Besides all these core features, the platform allows users to have private annotations on nodes and allows scientists to have public annotations that can be viewed by other users.

In summary, our collaborative science platform aims to revolutionize scientific research by providing a structured and organized approach to developing knowledge in any scientific domain.

1.2 Project Status

Since the launch of the project development process, our team created a GitHub repository and managed it with the purpose of conducting our work and communication. Firstly, all of the team members researched their favourite GitHub repositories individually and took note of their best practices for project management. Afterward, we created a wiki page to document them. Then, we generated separate wiki pages to introduce ourselves. We formed an issue template and a meeting notes template to keep our tasks and discussions organized. By using these templates, we documented all our meeting discussions, decisions and action items assigned to group members. We created a README file to provide a description of the project and introduce team members. Also, our wiki page can be accessed by this file.

To determine our project requirements, we set a meeting with our product owner. We prepared a list of questions and concerns to discuss with our product owner regarding the features and goals of the platform beforehand. Then, we organized and documented the requirements of our project. Based on the requirements, scenarios for Scientist/Contributor, Reviewer, Collaborator and Guest User were created. Then, our team developed high-level mock-ups for the platform considering requirements and user scenarios for web and mobile devices.

We prepared our UML diagrams starting from Use Case diagrams. These diagrams were created to show how our five different actors (Contributor, Reviewer, Guest, Basic User, Admin) interacts with the system. Additionally, we developed class diagrams to represent the structure of the system and the relationship between the classes. Our classes are as follows: Account Class, Guest User Class, Contributor Class, Reviewer Class, Admin Class, Basic User Class, Workspace Class, Entry Class, Node Class, Theorem Class, Question Class, Request Class, Proof Class, Collaboration Request Class, Review Request Class, Search Class, Semantic Tag Class, Annotation Class, Notification Class. Additionally, we developed sequence diagrams to illustrate the flow of events and interactions between different classes during scenarios, such as when a scientist creates a workspace.

We created a RAM to indicate the contributors of completed tasks. Moreover, we created our project plan and communication plan. We included those plans in the Milestone 1 Report.

2. List and Status of Deliverables

Deliverables

3.Evaluation of Deliverables

3.1 Project Repository

Our project repository is named bounswe2023group9 and 10 team members contribute to the repository. The project repository served as a central location for storing all of our project artifacts, including documentation, design files and issues.

On the home page of our repository, there is a README.md file that describes the purpose of our project, introduces team members and provides instructions to access our wiki pages. Our wiki homepage summarizes what we have done so far, lists our deliverables and provides links to relevant documentation and artifacts. Moreover, we organized our wiki sidebar to provide easy access to different sections, such as meeting notes and requirements. We maintained our project repository to make sure that it reflects the latest progress and changes in our project, and that all the necessary pages are up to date. To achieve this goal, we updated our repository frequently, and actively reviewed and responded to issues.

3.2 Requirements

Our requirements were carefully elicited and specified based on the needs of our different actors, such as Contributor, Guest, Reviewer, Collaborator, Basic User. We asked detailed questions to our product owner to understand his expectations and needs for the project.

We separated functional and nonfunctional requirements in our requirements document and made sure that all requirements were specific, measurable, achievable, relevant and time-bound. Furthermore, we numbered our requirements to organize them. In addition, we add a glossary section to define important terminology used in the requirements.

We have set several meetings to discuss these requirements by brainstorming and debating to ensure clarity and completeness. All team members actively participated in this process to make sure that all possible scenarios and requirements are captured.

3.3 Scenarios and Mock-ups

To ensure that our project meets the needs of our different actors, we created several scenarios and mock-ups to illustrate how each actor would interact with our platform. We used these mock-ups to gather feedback from our product owner and make sure that we are on the same page. Additionally, we revised and recreated our first draft of mock-ups based on the feedback we received from our product owner.

We created mock-ups for web and mobile interfaces by using drawing tools such as diagrams.net and Figma. These mock-ups helped us to visualize different functionalities of the platform and ensure that the platform satisfies requirements.

3.4 Software Design Documents in UML

3.4.1 Use Case Diagrams

To gain a better understanding of the functionalities of our project, we created diagrams that focused on the perspectives of our platform's user profiles. These diagrams illustrate the general interactions between users and the system/environment, while also answering important questions about the different types of users and their abilities. During this process, we uncovered communication and design issues related to the requirement elicitation process, which led us to revise our project requirements.

We splitted up groups and designed the diagrams using LucidChart. We identified five different types of users: Guest, Basic User, Contributor, Reviewer and Admin. We used the "include" arrow to indicate that a specific functionality is included in a use case, and the "extend" arrow to indicate that a particular functionality is not mandatory for a use case. By creating high-level diagrams, we were able to determine the user functionalities of our platform and how users interact with the system. The diagrams also helped us distinguish the capabilities of different user profiles.

3.4.2 Class Diagrams

In order to gain a more comprehensive understanding of how our system components are organized, we utilized class diagrams to focus on the class components and their relationships. These diagrams, with an object-oriented system model, outline the general structure of our system by listing class names, attributes, and methods, and provide more detailed information than use case diagrams.

To create these diagrams, we split into groups and utilized LucidChart. Through this process, we identified several classes and methods. We used aggregation arrows to indicate classes with their own lifecycle and composition arrows to indicate classes that are destroyed when their parent classes are destroyed. We also used inheritance arrows to indicate the inheritance relationship between classes. By visualizing the classes and their relationships, we were able to gain a more detailed understanding of the system components and their relationships from a lower-level perspective that is closer to implementation.

3.4.3 Sequence Diagrams

By creating both use case and class diagrams for our project, we were able to showcase the user interactions and system components, as well as the relationships between them. To further our understanding of the project, we also designed sequence diagrams, which detail the interactions between system components and how they handle a use case by showing the data flow between them. This process also allowed us to determine if our class identifications and use cases were sufficient to meet the project requirements.

Once again, we split into groups and utilized LucidChart to create these diagrams. We used object boxes and arrows to represent a use case, with black arrows indicating function calls or user actions and dashed arrows indicating message returns. Through visualizing the user sequences, we were able to identify errors in our class attributes and methods and made revisions accordingly.

Overall, the creation of these UML diagrams enabled us to outline the project's general structure and organization, which will ultimately aid us in the implementation process.

3.5 Communication Plan

We choose Discord as our main communication tool. We created a Discord channel with several channel categories for different purposes, including planning and general and specific discussions. We also used voice channels to conduct some of our meetings and to facilitate real-time discussions while working on our tasks collaboratively. Besides Discord, we also communicated through Whatsapp to send quick updates and reminders.

We had our weekly meetings scheduled for every Wednesday at 20.00. Except for a meeting, we were able to stick to our schedule and ensure that every member is present. Moreover, we had several small meetings with small groups of team members to discuss and complete subtasks.

We used GitHub to assign issues and track progress. We documented our meeting minutes and decisions on GitHub.

Lastly, we started to use a common Notion workspace where we can keep drafts of our work.

3.6 Project Plan and RAM

We prepared the Project Plan and RAM while preparing the Milestone report. For the RAM we created an excel spreadsheet with tasks accomplished by the team as rows and team members as columns. Everyone filled their own column to show whether they contributed or reviewed that task. We checked all the closed and open issues, revision history of wiki and notes taken during the meetings to gather the task history of our team.

We used ProjectLibre to create the Project Plan. In the project plan we extended the information provided in the RAM by adding the time interval that each task has been accomplished. We also constructed a Gantt Chart to better visualize our progress. We didn’t include any future planning to the project report, because we didn’t know what we will do next for the project.

While preparing the Project Plan and the RAM, we realized we didn’t do a good job of saving our progress to the repository. Some issues were left open due to the slow and (sometimes) ambiguous reviewing process. Some issues were opened before they were due and some were opened after the issue had been resolved. We will try to avoid these mistakes in the future by introducing new standards and tracking methods to the team.

4. Evaluation of Tools

While developing the project, we used different platforms and tools to speed up the process and work collaboratively. Each tool and platform helped us work as efficiently as possible. Since every team member could access other members' work, we were able to keep track of the progression of the tasks with the help of these tools. Additionally, the platforms that we have used helped us communicate easily and ask questions about ambiguous parts of the work. We avoid using complicated tools, since they would have slowed down us carrying out the project. We selected the tools which we used by considering their performance in terms of ease of use and simplicity.

4.1 GitHub

Github is the main tool that we have used so far. It is the platform in which we combine all the work we have done. It includes all the information about our project and what we have achieved up to now. By opening issues, we divided the tasks among the group members, asked questions about how we could develop our project, and requested reviews of other group members so that we could confirm our work. Github has been used at almost every part of the project. Every documentation, schema, diagram, research, and assignment has been listed in the Github page of our project. While issues helped us keep track of current tasks needed to be completed, wiki pages that we have created so far helped us collect all the materials produced during the design phase of the project.

Github is a great tool in terms of collective work, management and distribution of tasks. It eased and simplified our job considerably. It has played a critical role throughout the development of the project up until now.

4.2 Discord

Discord has been the main communication platform that we have used so far. We created a Discord server including all the members of the team. A group member was able to ask questions about the project in the relevant channels of the server to clarify his/her confusions. All the links and related files were shared to other team members via Discord. Additionally, we conducted our online meetings on our Discord server since the voice channels of Discord are a perfect tool for this purpose. Presence of multiple voice channels helped us work on more than one task simultaneously. Some materials such as diagrams, researches, and documentations were sent to our Discord server for approval since we uploaded our materials to our Github page once we all agreed to do so. In this manner, Discord served as an intermediate platform as well. One of the most important aspects of Discord for our project is that it included only project related materials since we avoid using it for our personal tasks.

4.3 Whatsapp

Whatsapp is mainly used for instant communication. It was the tool that we used when we needed to communicate to other members about urgent things. For instance, we opened polls to determine the meeting dates and inform other members of the team about tasks in case they may not have seen related issues in Github. Additionally, we kept track of who was coming to face-to-face meetings since we didn’t want anyone to miss the meetings. We also used Whatsapp to ask our team members when they would complete their tasks because some tasks needed previous ones to be completed. In addition, we usually asked help from other team members if there was a confusing part in a task that was assigned to us. Considering all of these, Whatsapp was our secondary platform that we used to communicate with each other and organize our work.

4.4 Diagrams.net

Diagrams.net is a free tool used to create flowcharts and diagrams. Almost all the team members were familiar with this tool. Therefore, we used Diagrams.net to create our mock-ups for web platforms. One drawback of Diagrams.net is that it can be difficult to create more complex designs, particularly those with a large number of interconnected elements or screens.

4.5 Figma

We used Figma for our Mock-ups for mobile devices. We choose to work with Figma since Figma's community provides a wealth of design resources such as icons, UI kits, color schemes and templates which help to speed up the design process while maintaining a consistent look throughout all screens. Unfortunately, using Figma requires a brief prior knowledge of how to use its tools. Therefore, we could not create all mock-ups with Figma.

4.6 Lucidchart

Lucidchart was mainly used to create use-case diagrams, class diagrams, and sequence diagrams. It is a perfect tool to create such diagrams. First of all, it is student-friendly. It has an EDU Free option when a student like us signs up by using his/her university e-mail address. Also, it has a vast library for different kinds of diagrams. All the templates that we needed to draw use-case diagrams, class diagrams, and sequence diagrams were present in Lucidchart. What is more is that many users can work on the same diagram at the same time. During our design period, Lucidchart accelerated our progress and helped us complete the diagrams in a short time. Ease of use and possibility of collaborative work were the main reasons why we used Lucidchart. In short, Lucidchart provided all the features that were needed to design and create diagrams of our project.

4.7 Notion

Notion is a free productivity and note-taking web application. It is a tool that we have listed various things about our project such as tasks, task divisions, and links of Lucidchart diagrams. We started using Notion after we were assigned to draw the use-case diagrams of the different kinds of users of our scientific collaboration platform. Since links of important documents may be lost in time, we put the links of the use-case diagrams of our project to the teamspace we opened in Notion. Additionally, the team members who were assigned to design diagrams are also mentioned in the Notion as well. We did the same thing for class and sequence diagrams, too. In short, Notion served us as a note-taking web application in which Lucidchart links, tasks, and drafts are listed.

4.8 Google Docs

Google Docs was another tool that we used to list and document things. A platform in which every team member can review, modify, and contribute to tasks was required. For instance, determining requirements of our scientific collaboration platform was a task all members had to contribute. All members of the group had to work on the same document at the same time. Therefore, a document every member had a permission to access and modify was needed. Google Docs was a perfect tool for this purpose since many people could work on the same document simultaneously. It has useful features such as highlighting, commenting, and suggesting organization, which leads to an increase in not only efficiency but also productivity. In addition to requirements, we used Google Docs to write the Milestone report.

5. Evaluation of Processes

5.1 Product Owner Meetings

We had two product owner meetings until the first milestone. During the first meeting with the product owner, we asked detailed questions about the requirements and functionalities of the platform. Afterward, the team discussed the requirements and documented them in detail. Based on these requirements, we created our first drafts of scenarios and mock-ups. In the second meeting, we presented our mock-ups and received feedback from the product owner. Mock-ups were revised and recreated based on the feedback to ensure that they align with the expectations of the product owner. Overall, meetings with the product owner enabled us to understand his expectations clearly.

5.2 Team Meetings

Weekly team meetings played a crucial role in ensuring that every member of the team was on the same page and working collaboratively toward achieving the project goals. During the weekly team meetings, we discussed our progress, identified potential roadblocks or challenges and brainstormed solutions to overcome them. Furthermore, we assign tasks to group members based on their skills and availability with proper deadlines. We took notes of decisions made and further action items to be taken, which were documented in the meeting notes. We concluded our meetings by summarizing key concepts and arranging the next meeting time.

We tried to conduct our meeting at most for one hour to ensure that they are efficient and effective. But, in some of the meetings we couldn't finish in time. To increase the efficiency of meetings, in the future plan, we may consider setting strict time limits and adhering to an agenda.

5.3 Issue Creation

After dividing tasks between team members, we created relevant issues on GitHub to track progress. These issues include detailed issue descriptions, assigned team members, labels for type of task, difficulty level, current status updates and priority levels along with due dates as well as a step-by-step plan to complete each issue. In order to streamline the process further we formed specific labels that categorize these different aspects, including the type of task being completed (design, documentation, etc.), and its overall difficulty level from the low effort to high-intensity workloads which helps us prioritize accordingly while also taking into account various sizes depending on how extensive they may be relative against others in comparison within our workload schedule.

Team members added relevant information to the issue, such as progress updates, questions or issues they faced during the tasks. Assignees changed label status from "In progress" to "needs review" when they are finished with the task. We made sure to double-check our work by reviewing each other's work to catch potential inconsistencies and misunderstandings.

However, some of the issues were not properly closed in time. Also, review requests were delayed due to ambiguity. To improve the issue completion process and prevent delays in the future, we need to establish clear guidelines regarding issue closure and review requests. Also, we should set more strict deadlines to be sure that our tasks are completed on time. In addition, we can show our work on tasks on the comments of the related issue in more detail rather than communicate internally.

6. Individual Contributions Reports

7. Deliverables

7.1 Project repository

Our project repository is named “bounswe2023group9”. It includes a README file in which we introduced our project and team briefly. An issue template is also present in the repository. Documentations about our scientific collaboration platform can be found in the wiki page of the repository.

7.2 Requirements:

7.2.1 Software Requirement Specification

The Software Requirement Specifications can be found in the Requirements Page in detail with its glossary.

7.2.2 Scenarios, and Mockups

We have seperated them into 4 according to the user types. All of them can be seen in their pages:

7.3 Software design documents in UML

7.3.1 Use Case Diagrams

Use Case Diagram can be seen by visiting Use Case Diagram page.

7.3.2 Class Diagrams

Class Diagram can be seen by visiting Class Diagram page.

7.3.3 Sequence Diagrams

We have divided Sequence Diagrams into sections of user types. They can be seen by visiting Sequence Diagrams page.

7.4 Project Plan

Bounswe2023group9_Page_1 Bounswe2023group9_Page_2 Bounswe2023group9_Page_3 Bounswe2023group9_Page_4 Bounswe2023group9_Page_5 Bounswe2023group9_Page_6 Bounswe2023group9_Page_7 Bounswe2023group9_Page_8 Bounswe2023group9_Page_9

7.5 RAM (Responsibility Assignment Matrix)

RAM_Page_1 RAM_Page_2 RAM_Page_3 RAM_Page_4 RAM_Page_5 RAM_Page_6 RAM_Page_7

7.6 Communication Plan

Communication

Meeting Schedule/Agenda

1- Determining note taker

  • a- Usually someone volunteers

  • b- If not, someone will be assigned randomly

2- General agenda of the meeting is filled by all team members through the last week and discussed in the meeting

3- Unfinished tasks are discussed and redistributed if necessary

4- Assignments of the week are discussed

5- Repositories of the previous years are examined to estimate the completion time of the assignments

6- After all tasks for the week has been established, they are distributed

  • a- First to volunteers

  • b- Then remaining tasks are distributed randomly and evenly

7- Establishing the reviewers and the deadlines of the tasks

8- A file to keep the next week's agenda is created for the team to fill through the next week