Merge pull request #31 from rproenza86/feat/us30/update-doc

feat: Update readme

README.md

@@ -1,13 +1,11 @@
-# [Unit Conversion Grading](https://unit-conversion-grader.web.app)
-
+# [Unit Measure Conversion Judge](https://unit-conversion-grader.web.app)
 
 > CI/CD powered by  [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions)
 
 | [Continuos Integration(CI)](https://en.wikipedia.org/wiki/Continuous_integration) | [Continuos Deployment(CD)](https://en.wikipedia.org/wiki/Continuous_deployment) |
 | :---: | :---: |
 | ![Pull Request Unit Test Check](https://github.com/rproenza86/unit-conversion-grader/workflows/Pull%20Request%20Unit%20Test%20Check/badge.svg)  | ![Firebase Hosting Deployment](https://github.com/rproenza86/unit-conversion-grader/workflows/Firebase%20Hosting%20Deployment/badge.svg)  |
 
-
 ## Table of Contents
 
 - [Description](#description)
@@ -21,26 +19,25 @@
 
 ## Description
 
-This is a web application for allowing science teachers to grade unit conversion problems submitted by students.
+This is a web application for science teachers. The web app can evaluate unit conversion problems validating the solutions submitted by students.
 
 ### How it works
 
-Teachers assign students unit-conversion problems on paper worksheets. After students turn in their completed worksheet, the teachers will use this web app enter the questions and student responses into a computer to be graded.
+Teachers assign students unit-conversion problems on paper worksheets. After students turn in their completed worksheet, the teachers will use this web app to enter the questions and student responses into a computer to be graded.
 
 **Students will convert the following units:**
 
-  - **Temperatures:** ​Kelvin, Celsius​,​ Fahrenheit​, and​ Rankine
-  - **Volumes**: ​Liters,​ ​Tablespoons​, ​Cubic-inches, Cups​,​ Cubic-feet, ​and​ Gallons
-
-Note: the app does not allow conversion between invalid units.
+- **Temperatures:** ​Kelvin, Celsius​,​ Fahrenheit​, and​ Rankine
+- **Volumes**: ​Liters,​ ​Tablespoons​, ​Cubic-inches, Cups​,​ Cubic-feet, ​and​ Gallons
 
+> **Note**: The app does not allow conversion between invalid units.
 
 ## Technical Information
 
-These project is a ReactJS, Github and Firebase workshop. The following technologies and methodologies were used to implement the application:
+These project is a *ReactJS, Github and Firebase workshop*. The following technologies and methodologies were used to implement the web application:
 
 - JavaScript Frameworks
-  -  ReactJS and Jest
+  - ReactJS and Jest
 - Components Libraries
   - Material Components for React (MDC React) by Google Material Design team
   - Ant Design by Ant Design Group
@@ -52,27 +49,40 @@ These project is a ReactJS, Github and Firebase workshop. The following technolo
 - Software Development Methodology
   - Scrum with Kanban influences
 
-
 ## Project Management
 
-Since this is a small project, I used GitHub Projects to manage the project though normally I would use Jira. Adopting Github organizational tooling to support the SDLC of this project.
+Since this is a small project, I used GitHub Projects to manage the project though normally I would use Jira or Rally. Adopted Github organizational tooling to support the SDLC of this project.
 
-Following a Scrum/Kanban methodology, the artifacts were mapped in the following manner:
+### Software Development Methodology
 
-- Product Backlog - Github Issues
-- Sprint Backlog - Github Projects - ToDo column
-- Product Increment - Github Projects Board
-- Epics - Github Milestone
-- Story - Github Issue
+Following a Scrum/Kanban software development methodology, the artifacts were mapped in the following manner:
 
-The stories where grouped in Epics, moved into the project board stages from ToDo - In Progress - Review in Progress - Reviewer Approved - Done.
+| Scrum/Kanban | Github |
+| :--- | :--- |
+| Product Backlog | Github Issues |
+|  Sprint Backlog  |  Github Projects (ToDo column) |
+|  Epics |  Github Milestone |
+|  Story | Github Issue  |
+|  Product Increment |   Github Projects Board |
 
-For development process I used the following branch-based workflow:
+The stories where grouped in Epics, moved into the project board stages from `ToDo` -> `In Progress` -> `Review in Progress` -> `Reviewer Approved` -> `Done`.
+
+Using **Templates** to created User Stories(Github Issues) and Pull Requests so there is an standard structure for each artifact following the best practices and capturing critical information.
+
+### Branching Model
+
+For the development process I used the following branch-based workflow:
+![branch-based-workflow](docs/images/branch-based-workflow.svg)
 
 1. Branch from master on each new code change request
-2. Prefix branch names with `{type of work}/us{issue number}/{description}` Ex. `feat/us21/sass-migration`
-3. To merge new code additions a Pull Request is created, each PR is linked to a given Issue, the PR is validated running by the CI and is it pass the checks and coverage threshold it will be merged into the master branch
-4. On code commit into the master branch a CD process it triggered, unit tests are ran and on success the app is build and deployed to Firebase hosting
+2. Prefix branch names with `{type of work}/us{issue number}/{description}`
+   > Ex. `feat/us21/sass-migration`
+3. To merge new code additions:
+   1. One Pull Request is created.
+   2. Each PR is linked to a given Issue.
+   3. The PR is validated by running the CI checks.
+   4. Once passed the checks and coverage threshold, the PR can be merged into the master branch.
+4. On code commits into the master branch a CD process is triggered, unit tests are ran and on success, the app is build and deployed to Firebase hosting
 5. Once the PR is merged the linked issue is closed automatically and moved to the Done stage
 
     - Created 4 epics/milestones
@@ -81,28 +91,27 @@ For development process I used the following branch-based workflow:
     - The Project board has automation in place to move stories from stages. Ideally I would created one Github Project on this repo for each sprint but I consider it overkill for these small project
 ![github-projects-board](docs/images/github-projects-board.png)
 
-## Continuous Delivery
+## Continuous Delivery Practice
 
-Using Continuous Integration as software development practice to automate the code testing process and Continuous Delivery to automating the entire software release process.
+This project use **Continuous Integration** as software development practice to automate the code testing process and it use **Continuous Delivery** to automate the software release process.
 
-To support the CI/CD initiative two automation work load were created:
+To support the CI/CD practices, two automation workloads were created:
 
-1. For CI [Pull Request Unit Test Check](.github/workflows/pullrequesttest.yml)
-2. For CD [Firebase Hosting Deployment](.github/workflows/hostingdeployment.yml)
+1. For CI the [Pull Request Unit Test Check](.github/workflows/pullrequesttest.yml) workload was created.
+2. For CD the [Firebase Hosting Deployment](.github/workflows/hostingdeployment.yml) workload was created.
 
 ## How to use
 
 ### Web application access
 
-The web application is accessible on the next url : https://unit-conversion-grader.web.app
+The web application is publicly accessible on the next url : https://unit-conversion-grader.web.app
 
+> Short video demo
 ![web-app-demo](docs/images/web-app-demo.gif)
 
-<!-- TODO: Update video with better and shorter capture -->
-
 ### Development Operations
 
-In the project directory, you can run:
+To run the web app locally, from the project directory, you can execute the next commands:
 
 #### `npm start`
 
@@ -139,4 +148,4 @@ Deploys the latest build to Firebase hosting.
 [![license](https://img.shields.io/github/license/rproenza86/events-distributor.svg)](https://github.com/rproenza86/events-distributor/blob/master/LICENSE)
 
 - **[GNU General Public License version 3](LICENSE)**
-- Copyright 2025 © <a href="http://raulproenza.page" target="_blank">Raul Proenza</a>.
+- Copyright 2025 © <a href="http://raulproenza.page" target="_blank">Raul Proenza</a>