Development Practices
This document serves to inform on the Project Management and Technical Development frameworks used in the project.
1. Project Management
1.1. Scrum (Agile Model)
1.2. Kanban Boards
1.3. UML Diagrams
1.4. Code Review
1.5. Testing
1.6. Qualitative Evaluation
1.7. Errors
2. Technical Development
2.1. Flask
2.2. Model View Controller (MVC)
2.3. RESTful API
2.4. Data Normalization
Software Development is a complex topic that has many models and frameworks. Thankfully for Orbital and our Mentor, the development team had a chance to learn about the many practices used in Software Engineering. This section will explain the methodologies and frameworks used in project management.
Scrum is a framework used under the Agile software development model,
and the general process can be explained in the diagram above. It serves to break a team's work into goals that can be achieved within a certain time frame.
For our project, Orbital is already designed to have three one-month long periods between each Milestone submission.
With only 2 members in the team and just 3 months to complete the project, there needs to be an adjustment to the framework to for our needs.
This includes having both members as part of the Development Team, with 1 member taking the role of the Product Manager, and the other taking the role of the Scrum Master.
For our documentation, User Guides represent guidance on Business Requirements, while the Developer Guide represents guidance on the Product Development aspect of the project.
With the help of our Mentor, the team has also organised the relevant Sprint Review, on 12 June, and Sprint Retrospective, on 9 & 22 June. The Sprint Review dicussed the completed features, and the features that were needed to be implemented next. The Spring Retrospectives discussed what went well in the project up to that point, whether there needed to be improvements, and how the improvements were to be made. Improvements discussed on 9 June included the Database Design, Scrum framework application, and software engineering practices, while on 22 June, it was focused on Milestone 2 requirements which included Testing.
Unsurprisingly, GitHub is used as the host for version control with Git, so its features should be used to a great extent in terms of the software engineering aspect of the project.
Kanban boards are a feature used under the Projects section of each GitHub repository, and are extremely useful in providing an overview of, and tracking the work at various stages of the project.
For most people, reading long lines of text to explain a concept can be downright impossible without any diagrams. This project also then uses UML Diagrams to explain the flow of the logic which can be found in abundance in the Developer Guide. Explanations of some of the Diagrams used can also be found in the Documentation section
In a software development project, version control is highly essential in making sure that the history of code development is logged. Bugs and features can pop up in the process of upgrading and adding features in the project, so making sure that is possible to retrieve an older, working version of the code is important. Git is the common and obvious choice to do so, and GitHub is highly convenient site to host the version control. The team also makes use of the Pull Requests (PRs) and Code Review present in GitHub to protect the main code located in the master branch. With two members, in the team, there is implicit review of code that one member is attempting to merge in the PR by the other member. The advantage in conducting the code reviews is that there is more than one person involved in detecting any problems or bugs faced, ensuring higher quality code. Examples of the Version Control & Code Review practice can be found on the PR page of this repository.
It is important to ensure that the code continues to work even with constant updates. Python's own unittest module can be used for Unit Testing, Codecov measures code coverage, while Travis does Integration Tests.
The Developer Guide covers testing in greater detail.
A Cognitive Walkthrough by the development team was done and to complement the walkthrough, a self/expert evaluation was used. Heuristic Evaluation - using Nielsen Heuristics - was used during the evaluation. Details on the 10 heuristics can be found on the link. Some of the heuristics the team managed to address were to make the application match the real world, providing user control and freedom, consistency, error prevention, minimalistic design, error recovery, and finally help and documentation. The walkthroughs served to allow the developers to further improve on Knewbie to make a better user experience.
The team also collected user feedback through surveys. The surveys were done in two phases. In the first phase, users were made to access the user guides for both, the educator, and the student versions. Both of which can be accessed from our wiki page. They were also asked to try out the high-fidelity prototypes for students and educators. The questionnaire can be accessed through this link. Hence, the feedback were mostly regarding user interface and user experience. A summary of the feedback can be found on these slides.
For the second phase, users were were able to experience the actual Knewbie web application before providing feedback. This included the quality of the applications, bugs, areas for improvement and even feature requests.
Through self-evaluation and unit testing, the team discovered that error prevention mechanisms and documentation would greatly improve the User Experience on the web application. We are able to prevent most errors by using Unit Testing & Integration Testing methods earlier, as well as designed error pages from HTTP errors that may occur from typical usage of the site's features. The errors - which include 403, 404, 410, 500 errors - can be found to be handled in the errors directory, with the HTML webpages in the templates/errors directory. The table below shows the messages seen by users for the 4 errors mentioned.
| Status Code | Message |
|---|---|
| 403 Forbidden | You do not have permission to access this page. |
| 404 Not Found | The page you are looking for isn't here. |
| 410 Gone | The page is permanently deleted. |
| 500 Internal Server Error | There is some issue on our end. Please report this bug! |
An example of a bug that was fixed includes an error faced when submitting no option for the quizzes offered in the app. This will cause a 500 error, due to having no data be sent in the POST request of the submission of the question. This was subsequently prevented when adding a required attribute to the <form> tag containing the data to be sent, ensuring that a user cannot accidentally answer a question with no data.
Flask is a micro and lightweight web development framework that makes use of Python to build web applications. Flask was chosen for development due to its ease of use, along with the developer friendly syntax of Python, a language which the development team was already familiar with. It is known to be configurable. This tutorial made by Miguel Grinberg also proved to be extremely useful in the implementation of the various features in the platform. It might be helpful to mention that Django - a full-stack web development framework also in Python - was also a possible choice, but the development team had previous experience with Flask leading to its choice over Django.
Model-view-controller is a software design framework for developing user interfaces, and due to its popularity, was used in the project. Its main feature is separation of the different areas of development. Further explanation on how it is applied in Flask can be found in the Developer Guide.
REST, which stands for REpresentation State Transfer, is an architectural style used in defining constraints for creating web applications. Our web application makes use of the RESTful API when making HTTP requests such as GET or POST requests.
The methods or type of requests (GET, PUT, POST, PATCH, DELETE) are used to perform one of four possible actions from CRUD (Create, Read, Update, Delete). Each of our user stories also has a corresponding CRUD action which makes it easier for us to streamline the requests. The user stories can be found in our Developer Guide.
There are multiple ways to design a database, and doing Database Normalization can ensure that the design leads to better efficiency overall. Data Normalization eliminates redundant data and ensures dependencies are logically stored. The database design should satisfy 3NF (3rd Normal Form) normalization.
Generally 3NF normalization would mean adhering to the following points:
- Only single valued columns
- Values of each column should be of the same type
- All columns in the table should have a unique header
- Order of data does not matter
- There should not be partial dependencies
- There should not be transitive dependencies