Adding to and reworking README.md, INSTALL.md, and INSTALL_CANVAS.md

INSTALL.md

@@ -1,5 +1,7 @@
 # Installing UDOIT
-UDOIT can be installed on your own existing servers with the following instructions. UDOIT is also available as a hosted and maintained product by [Cidi Labs](https://cidilabs.com). UDOIT is built using the [PHP Symfony Framework](https://symfony.com).
+UDOIT can be installed on your own existing servers with the following instructions. It is also available as a hosted and maintained product by [Cidi Labs](https://cidilabs.com). 
+
+UDOIT is built using the [PHP Symfony Framework](https://symfony.com).
 
 ## System Requirements
 The system requirements depend on how you install UDOIT.
@@ -19,25 +21,29 @@ The system requirements depend on how you install UDOIT.
 
 ## Download the Code
 ### Option 1: Git (Strongly recommended)
-This method is strongly recommend as it allows UDOIT to be updated through a simple command on the terminal: `git pull`. It also lets you roll back to previous versions if needed. Follow these steps:
+This method is strongly recommended as it allows UDOIT to be updated through your computer terminal using a simple command: `git pull`.
+
+To quickly access your terminal:
+- On Windows: Press `Windows key + X` and select `PowerShell`. This will open a window for you to navigate to the folder you want UDOIT installed in.
+- On MacOS: Press `Cmd + Space`, type in `Terminal` and hit `Enter`.
+- On Linux: Press `Ctrl + Alt + T` and search for `Terminal` or `Console`.   
+>Note: Continuing with the following process in the `main` branch may mean working with changes in the latest development cycle. If you want to work on a stable release, go to the [release tags](https://github.com/dmols/UDOIT/tags) to find the version you want to work with, and follow the installation instructions from there!
+
+Follow these steps:
 
 1. Install Git on your server (https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 2. Create a folder/directory in which UDOIT will reside (e.g `UDOIT`) and navigate to it.
 3. Inside the UDOIT directory, run `git clone git@github.com:ucfopen/UDOIT.git . ` (The . is important; It tells Git to download the files to the current directory.)
 
 ### Option 2: Zip File
-If you prefer not to use Git, you can download the zip file of the latest release from the [Releases Page](https://github.com/ucfopen/UDOIT/releases).  Unzip it in the directory in which UDOIT will reside.
+If you prefer not to use Git, you can download the zip file of the latest release from the [Releases Page](https://github.com/ucfopen/UDOIT/releases). Unzip it in the directory in which UDOIT will reside.
 
-## .ENV Setup
+## .ENV File Setup
 UDOIT stores configuration variables in a `.env` file. To create it:
 
-1. Inside the UDOIT directory, run the following command in shell:
-```
-cp .env.example .env
-```
-This command copies the `.env.example` into `.env`, creating the `.env` file in the process if it does not exist.
+1. Inside the UDOIT directory, run `cp .env.example .env` in the terminal.
 
-2. Open `.env` with a text editor (i.e. Notepad, VS Code, etc.) and make the necessary changes to the following variables:
+2. Open the `.env` file with a text editor (i.e. Notepad, VS Code, etc.) and make the necessary changes to the following variables:
    - `APP_ENV`: If you are setting up a development environment, change this to `dev`. Otherwise, leave it as `prod`.
    - `DATABASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to your database URL.
    - `BASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to the URL of your instance of UDOIT.
@@ -48,6 +54,7 @@ This command copies the `.env.example` into `.env`, creating the `.env` file in
 
 ## Installation
 
+There are a couple different ways you can configure your UDOIT instance. We strongly recommend the Docker installation if possible, as it tends to be a lot more straightforward and easier to debug.
 ### Option 1: Docker
 We provide a fast and simple way of setting up a local UDOIT instance through Docker.
 
@@ -60,79 +67,65 @@ UDOIT uses Composer to install PHP dependencies. Running the following command w
 
 #### 3. Build the Containers
 
-```
-    make start
-```
+- Run the command `make start` on your terminal. 
+
 
 *Note: This may take a while to fully initiate. This is normal.*
 #### 4. Set Up Database
 
-The following command applies migrations necessary to set up the database to store all UDOIT data. Please make sure the containers have fully spun up before running this command.
-```
-    make migrate
-```
+The following command applies migrations necessary to set up the database to store all UDOIT data. Please make sure the containers have fully spun up before proceeding.
+
+- Run `make migrate`.
 
-Running this will give the following warning:
+Running this command will give the following warning:
 
 > WARNING! You are about to execute a migration in database "udoit3" that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
 
-Type `yes` and proceed. The warning is expected and is a non issue.
+Type `yes` and proceed. The warning is meant to deter you if you already have data in the database but we don't yet.
 
 > Note: You will need to run this command whenever you update to a new version of UDOIT.
 
-UDOIT should be installed and running as Docker containers.
+UDOIT should be installed and running as Docker containers. You won't see any data in the tables yet and that is normal in this step of the process.
 
-#### To stop the UDOIT containers, run the following command:
-```
-    make down
-```
+#### Stopping the UDOIT containers
+To stop the UDOIT containers, run `make down` on your terminal.
 
-Please be sure to review the `makefile` for more information on what this command and others do.
+*Please be sure to review the `Makefile` for more information on what this command and others do.*
 
 If UDOIT is running without errors, you can move on to [installing it for your LMS](#connecting-udoit-to-an-lms)! If you're encountering errors, please check out the [wiki](https://github.com/ucfopen/UDOIT/wiki).
 
 ### Option 2: Manual Installation
-If you prefer not to use Docker, the process is more complicated:
+If you prefer not to use Docker, the process is more complicated.
 
 #### 1. Configuring your Web Server
  The details of configuring a web server with PHP are out of the scope of this README. You should configure your web server to point to UDOIT's "public" folder as the web root folder. Doing this will hide the configuration and source files so that they are not web accessible. It will also clean up your URL structure so that you don't need to include the "public" folder in any of the URLs to UDOIT.
 
 If you are using NGINX as your web server, you can use the `build/nginx/nginx.conf` file as a starting point.
 
 #### 2. Installing Composer Dependencies
-UDOIT uses Composer to install PHP dependencies. Follow the upstream documentation on [Composer Installation](https://getcomposer.org/download/) to install `composer.phar` into the project root, then run the following:
+UDOIT uses Composer to install PHP dependencies. Follow the upstream documentation on [Composer Installation](https://getcomposer.org/download/) to install `composer.phar` into the project root. After that, you can proceed to this step.
 
-    php composer.phar install --no-dev
+- Run `php composer.phar install --no-dev`.
 
 > Remove the `--no-dev` flag if you set `APP_ENV=dev` in your `.env.local` file.
 
 #### 3. Database Setup
 While UDOIT is configured to use MySQL or MariaDB by default, Symfony can be configured to work with other databases as well. See the Symfony documentation for details.
 
-Use Symfony to create the database with this command:
+- Use Symfony to create the database by running `php bin/console doctrine:database:create`.
 
-    php bin/console doctrine:database:create
+- Once the database is created you can populate the databasee by running `php bin/console doctrine:migrations:migrate`.
 
-Once the database is created you can populate the database with the following command:
+Tip: If you are getting errors when running the migration script try running `php bin/console doctrine:schema:update --force`.
 
-    php bin/console doctrine:migrations:migrate
-
-Tip: If you are getting errors when running the migration script try the following:
-
-    php bin/console doctrine:schema:update --force
-
-If you are operating in a production environment you will need to generate the doctrine proxy classes by running the following command:
-
-    php bin/console cache:warmup --env=prod
+If you are operating in a production environment you will need to generate the doctrine proxy classes by running `php bin/console cache:warmup --env=prod`.
 
 #### 4. JavaScript
-UDOIT uses [node](https://nodejs.org) and [yarn](https://yarnpkg.com/) to compile the JavaScript. Install Node and Yarn on your system, then run:
-
-    yarn install
+UDOIT uses [node](https://nodejs.org) and [yarn](https://yarnpkg.com/) to compile the JavaScript. Install Node and Yarn on your system, then follow these steps.
 
-To build the JavaScript files for production, run the command:
+- Run `yarn install`.
 
-    yarn build
+- To build the JavaScript files for production, run `yarn build`.
 
 ## Testing successful installation
 While UDOIT is an LTI tool that only functions fully within an LMS, you can plug the following URL in your browser to test if UDOIT is installed correctly:

INSTALL_CANVAS.md

@@ -14,15 +14,17 @@ UDOIT requires an API developer key since all course data is gathered through th
 
 ### Steps to Create an API Key
 1. Navigate to `Developer Keys` in the root account menu.
+<img src="./assets/mediaAssets/installation-images/dev-keys-location.png" alt="Screenshot showing the Developer Keys option in the Canvas root account menu" width="500" height="auto">
 2. Choose to add a `Developer Key` => `API Key`
+<img src="./assets/mediaAssets/installation-images/api-key-install.png" alt="Screenshot showing the Developer Keys option in the Canvas root account menu" width="600" height="auto">
 3. Provide values for the following fields:
-   * Key Name: i.e. UDOIT 3 API
+   * Key Name: i.e. UDOIT API
    * Owner Email
    * Redirect URIs: <YOUR_UDOIT_BASE_URL>/authorize/check
    * Redirect URL (Legacy) : *SKIP*
    * Vendor Code : *SKIP*
    * Icon URL: <YOUR_UDOIT_BASE_URL>/build/static/udoit_logo.svg
-   * Notes : *Optional*
+   * Notes (Optional):
      * These are only seen by other LMS admins
    * Client Credentials Audience: Canvas
    * Enforce Scopes
@@ -34,57 +36,53 @@ UDOIT requires an API developer key since all course data is gathered through th
 ### Scopes
 We strongly recommend you enforce scopes with your API key. The following scopes must be enabled for UDOIT to work.
 
-* accounts
+* Accounts
   * url:GET|/api/v1/accounts
   * url:GET|/api/v1/accounts/:id
   * url:GET|/api/v1/accounts/:account_id/sub_accounts
-* announcements_api
+* Announcements
   * url:GET|/api/v1/announcements
-* assignments_api
+* Assignments
   * url:GET|/api/v1/courses/:course_id/assignments
   * url:GET|/api/v1/courses/:course_id/assignments/:id
   * url:PUT|/api/v1/courses/:course_id/assignments/:id
-* context_module_items_api
-  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items
-  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items/:id
-  * url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id
-* context_modules_api
-  * url:GET|/api/v1/courses/:course_id/modules
-  * url:GET|/api/v1/courses/:course_id/modules/:id
-  * url:PUT|/api/v1/courses/:course_id/modules/:id
-* courses
+* Courses
   * url:PUT|/api/v1/courses/:id
   * url:GET|/api/v1/courses/:id
-  * url:POST|/api/v1/courses/:course_id/files
   * url:GET|/api/v1/courses/:course_id/users
-* discussion_topics
+  * url:POST|/api/v1/courses/:course_id/files
+* Discussion Topics
   * url:GET|/api/v1/courses/:course_id/discussion_topics
-  * url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id
-* discussion_topics_api
   * url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id
-* files
+  * url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id
+* Enrollment Terms
+  * url:GET|/api/v1/accounts/:account_id/terms
+* Enrollments
+  * url:GET|/api/v1/courses/:course_id/enrollments
+* Files
   * url:GET|/api/v1/courses/:course_id/files
   * url:GET|/api/v1/courses/:course_id/files/:id
-* quizzes/quiz_questions
+* Modules
+  * url:GET|/api/v1/courses/:course_id/modules
+  * url:GET|/api/v1/courses/:course_id/modules/:id
+  * url:PUT|/api/v1/courses/:course_id/modules/:id
+  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items
+  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items/:id
+  * url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id
+* Pages
+  * url:GET|/api/v1/courses/:course_id/pages
+  * url:GET|/api/v1/courses/:course_id/pages/:url_or_id
+  * url:PUT|/api/v1/courses/:course_id/pages/:url_or_id
+* Quiz Questions
   * url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/questions
   * url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/questions/:id
   * url:PUT|/api/v1/courses/:course_id/quizzes/:quiz_id/questions/:id
-* quizzes/quizzes_api
+* Quizzes
   * url:GET|/api/v1/courses/:course_id/quizzes
   * url:GET|/api/v1/courses/:course_id/quizzes/:id
   * url:PUT|/api/v1/courses/:course_id/quizzes/:id
-* terms_api
-  * url:GET|/api/v1/accounts/:account_id/terms
-* users
+* Users
   * url:GET|/api/v1/users/:id
-* wiki_pages_api
-  * url:GET|/api/v1/courses/:course_id/pages
-  * url:GET|/api/v1/courses/:course_id/pages/:url_or_id
-  * url:PUT|/api/v1/courses/:course_id/pages/:url_or_id
-
-* enrollments_api
-  * url:GET|/api/v1/courses/:course_id/enrollments
-  *   
 
 ## Create an LTI Developer Key
 UDOIT uses LTI 1.3 to integrate with the LMS.
@@ -95,7 +93,7 @@ Follow the steps below, replacing `<YOUR_UDOIT_BASE_URL>` with the `BASE_URL` va
 1. Navigate to `Developer Keys` in the root account menu.
 2. Choose to add a `Developer Key` => `LTI Key`
 3. Provide values for the following fields:
-   * Key Name: i.e. UDOIT 3 LTI
+   * Key Name: i.e. UDOIT LTI
    * Owner Email
    * Redirect URIs: <YOUR_UDOIT_BASE_URL>/lti/authorize/check
    * Configure methods
@@ -119,34 +117,31 @@ Follow the steps below, replacing `<YOUR_UDOIT_BASE_URL>` with the `BASE_URL` va
 UDOIT is built to support more than one LMS instance. For this purpose, we have an `institution` table that must be populated with the LMS information.
 
 1. Inside the UDOIT directory, run `cp .ins.env.example .ins.env`
-2. open `.ins.env` with a text editor (i.e. Notepad, VS Code, etc.)
+2. Open `.ins.env` with a text editor (i.e. Notepad, VS Code, etc.)
 3. Fill in the fields with the appropriate values
 - `TITLE` = Your institution's name
 - `LMS_DOMAIN` = The Canvas domain name of your institution (i.e. `myschool.instructure.com`)
 - `LMS_ID` = `canvas`
-- `LMS_ACCOUNT_ID` = The Canvas account ID (as a string) where UDOIT will be installed
-- `CREATED` = Date in this format: `2021-06-08`
-- `STATUS` = `1` if you are using MySQL or MariaDB (or Docker), `true` if you are using PostgreSQL
+- `LMS_ACCOUNT_ID` = The Canvas account ID (as a string, i.e `"1"` instead of `1`) where UDOIT will be installed.
+- `CREATED` = Date in the format `YYYY-MM-DD` (i.e. `2026-03-27`)
+- `STATUS` = `1` if you are using MySQL or MariaDB (or Docker), `true` if you are using PostgreSQL.
 - `VANITY_URL` = Your LMS vanity URL (i.e. `canvas.myschool.edu`)
-- `METADATA` = Optional. Institution-specific settings, such as language or excluded tests. Text representation of a JSON object. (i.e. `{"lang":"en"}`)
+- `METADATA` (Optional) =  Institution-specific settings, such as language or excluded tests. Text representation of a JSON object. (i.e. `{"lang":"en"}`)
 - `API_CLIENT_ID` = The ID of the developer API key you created earlier
 - `API_CLIENT_SECRET` = The secret for the API key you created earlier
 
-With all the values now set up, you're ready to run the command that will automate the creation of your `institutions` table! Run the following command if you have a MySQL database setup:
-```
-make ins-mysql
-```
-Or this one if you have a PostgreSQL setup:
-```
-make ins-psql
-```
+With all the values now set up, you're ready to run the command that will automate the creation of your `institutions` table!
+
+- Run `make ins-mysql` if you have a MySQL database setup.
+- Run `make ins-psql` if you have a PostgreSQL database setup.
+
+
 Your database should now show a new row in the `institution` table, containing all the values you input above.
 
 
 ## .ENV Setup
 For cloud-hosted canvas instances, the default value for the `JWK_BASE_URL` environmental variable will work out of the box. If you are not cloud-hosted, you may need to change the value of this variable in `.env.local` to match your canvas instance.
 
----
 ## Install the App
 UDOIT now needs to be added to an account in Canvas. Follow these steps to add the LTI tool to an account:
 1. Copy the `Client ID` from the developer LTI key created earlier.

README.md

@@ -6,6 +6,8 @@ UDOIT enables faculty to identify accessibility issues in Canvas by Instructure.
 
 UDOIT was originally developed by the University of Central Florida (UCF) in 2014. In 2020, UDOIT was in need of a code refresh and UCF partnered with Cidi Labs to rewrite UDOIT from the ground up.
 
+Since then, it has strayed quite a bit from the licensed version Cidi Labs provides, while still providing comprehensive results and intuitive design changes. We continue to make this tool better and offer easier ways to make all course content accessible.
+
 ## Prerequisites
  - PHP 8.1, 8.2
  - Symfony
@@ -21,18 +23,17 @@ To complete this installation you will need the following skills:
 * MySQL familiarity
 * LMS admin permissions
 
-UDOIT is built using PHP, the Symfony framework, the React framework, the Instructure UI component library, and other open source libraries. However, knowledge of PHP or Javascript is _**NOT REQUIRED**_ for installation.
+UDOIT is built using PHP, the Symfony framework, the React framework, and other open source libraries. However, knowledge of PHP or Javascript is _**NOT REQUIRED**_ for installation.
+
+*Note: If you are using version 3.5 or earlier, UDOIT will also require the Instructure UI component library.*
 
 ## Where to Start
-**Tip:** Join the [UCF Open Slack community](https://dl.ucf.edu/join-ucfopen).  They can help solve any issues you may encounter.
+1. Join the [UCF Open Slack community](https://dl.ucf.edu/join-ucfopen). You are likely to find one of the developers assisting other users with similar issues you may encounter in your development process.
 
-1. Start the installation process by setting up UDOIT. Instructions are in [INSTALL.md](INSTALL.md).
+2. Start the installation process by setting up UDOIT. Instructions are in [INSTALL.md](INSTALL.md).
 
 2. Once UDOIT is running on your web server you need to configure your LMS. Instructions for the different LMS's are in `INSTALL_<LMS_NAME>.md`.
 
-## Installing UDOIT on Heroku
-UDOIT can be installed on your own existing servers, but we've also configured an easy install to a Heroku server. Check out the [HEROKU.md Readme](HEROKU.md) for more information.
-
 ## Contributing
 
 Like any other open source project, UDOIT relies on contributions from the community to improve the tool.  If you are interested in contributing to UDOIT, follow the instructions in [CONTRIBUTING.md](CONTRIBUTING.md).