do some revisions to the features text

docs/teachertool.md

@@ -2,143 +2,169 @@
 
 ## Overview
 
-The teacher tool is a mechanism for constructing a checklist of requirements and running that list automatically against projects in quick succession. This allows teachers to build a checklist, then easily evaluate any number of projects based on that checklist. Projects must be evaluated one at a time, but with auto-run enabled, you can update the loaded project by providing a new share link, at which point the rules will automatically be re-run on the new project.
+The [Teacher Tool]( https://microbit.makecode.com/beta--eval) is a mechanism for constructing a checklist of requirements for an assignment and running that list automatically against projects in quick succession. This allows teachers to build a checklist, then easily evaluate any number of projects based on that checklist. Projects are evaluated one at a time, but with auto-run enabled, you can update the loaded project by providing a new share link, at which point the rules will automatically be re-run on the new project.
 
-You can access the beta version of the teacher tool here: https://microbit.makecode.com/beta--eval
+[Teacher tool video/gif goes here]
 
-## Tool Features
+## Teacher Tool Features
 
 ### Creating, Editing, and Running a Checklist
 
 #### 1. Creating a new rubric
 
-A user can create a new rubric using the "New Rubric" card (or from the "..." action menu). If there is already an "in progress" checklist, a warning will appear asking if it is okay to overwrite it.
+A user creates a new rubric using the **New Rubric** card (or from the **...** action menu). If there is already an "in progress" checklist, a warning will appear asking if it is okay to overwrite it.
 
 ![New Rubric](/static/teachertool/new-rubric.png)
 
 ![New Rubric from menu](/static/teachertool/new-rubric-from-menu.png)
 
 #### 2. Naming a checklist
 
-User can give the checklist a name
+The checklist is given a name.
 
 ![Checklist name](/static/teachertool/checklist-name.png)
 
 #### 3. Add Criteria
 
-User can add criteria from the catalog using the "Add Criteria" button. Some criteria (like `[block] used [count] times`) can be added multiple times, others (like `Read a GPIO pin` can only be added once)
+One or more **_criteria_** are added from the catalog using the **Add Criteria** button.
 
 ![Add Criteria](/static/teachertool/add-criteria.png)
 
-![Criteria items](/static/teachertool/criteria-items.png)
+Some criteria (like `[block] used [count] times`) can be added multiple times, others (like `Read a GPIO pin` can only be added once).
 
-#### 4. Remove Criteria
+![Criteria items](/static/teachertool/criteria-items.png)
 
-User can remove criteria using the trash button
+#### 4. Fill in Parameters
 
-![Remove Criteria](/static/teachertool/remove-criteria.png)
+Parameters for the criteria item are filled in. Here are the parameter types:
 
-#### 5. Fill in Parameters
+- **Numeric** parameters have a small input and only allow number inputs.
+- **String** parameters can have medium and long sized inputs.
+- **Block** parameters should open a block-picker modal.
+- **Empty** parameters appear in an error state until they have values.
+
+![Criteria parameters 1](/static/teachertool/parameters-1.png)
 
-User can fill in parameters:
+Parameter options are displayed and then selected.
 
-- Numeric parameters have a small input and only allow number inputs
-- String parameters can have medium and long sized inputs
-- Block parameters should open a block-picker modal
-- Empty parameters appear in an error state until they have values
+![Criteria parameters 2](/static/teachertool/parameters-2.png)
 
-![image](/static/teachertool/parameters-1.png)
+![Criteria parameters 3](/static/teachertool/parameters-3.png)
 
-![image](/static/teachertool/parameters-2.png)
-
-![image](/static/teachertool/parameters-3.png)
+#### 5. Remove Criteria
 
-6. User can load a project into the project view by pasting in a share link or share id
+A criteria item is removed using the **trash** button.
+
+![Remove Criteria](/static/teachertool/remove-criteria.png)
+
+#### 6. Load a project
+
+A project into the project view by pasting in a share link or share ID.
 
-- The project should load in read-only mode
-- The project title should appear at the top of the project view
-
 ![A loaded project](/static/teachertool/loaded-project.png)
 
+The project will load in read-only mode with the project title appearing at the top of the project view.
+
 ![Project validation](/static/teachertool/validate-me.png)
 
-7. With a project loaded, user can run the checklist and see results by clicking the "Run" button
+#### 7. Run the checklist
 
-- Button is disabled without loaded project
+With a project loaded, the checklist can run. The results are shown after clicking the **Run** button.
 
 ![Run checklist](/static/teachertool/run-checklist-button.png)
 
+The results view lists each criteria with its outcome.
+
 ![Checklist execution](/static/teachertool/checklist-execution.png)
 
+**Note**: the **Run** Button is disabled without loaded project.
+
 ### Editing Results
 
-1. User can add feedback/notes using the "Add Notes" button
+#### 1. Add feedback and notes
 
-- The feedback box should resize to fit its content
-- Feedback is persisted if the user re-runs the rules using the "Run" button
+Feedback and notes are added using the **Add Notes** button. The feedback box should resize to fit its content as notes are added. The original feedback remains even if you re-run the rules using the **Run** button.
 
 ![Editing results](/static/teachertool/editing-results-1.png)
 
 ![Editing results](/static/teachertool/editing-results-2.png)
 
 ![Editing results](/static/teachertool/editing-results-3.png)
 
-4. User can edit an outcome using the provided dropdown
+#### 2. Edit outcomes
+
+An outcome is edited using the provided dropdown.
 
 ![Edit outcome](/static/teachertool/edit-outcome-1.png)
 
+The new selected outcome.
+
 ![Edit outcome](/static/teachertool/edit-outcome-2.png)
 
 ### Result Clearing and Auto-Run
 
-1. If auto-run is **disabled**, a result's outcome (i.e. "Looks good", "Needs work", etc...) should be set to "Not started" automatically when any of any of the following conditions are met:
-
-- It is newly added (should default to the "Not Started" state)
-- A parameter in a rule is changed (only the affected rule should enter the "Not Started" state)
-- The loaded project changes (all rules should be set to "Not started")
-
-2. Auto-run can be toggled on/off using the button in the menu.
+#### 1. Toggling Auto-run
+
+Auto-run is toggled either **on** or **off** using the button in the menu.
 
 ![Auto-run button](/static/teachertool/autorun-button.png)
-
-3. If auto-run is **enabled**, any rules that enter the "Not started" state from the above conditions should immediately and automatically get re-run and have their results updated.
+
+#### 2. Auto-run disabled
+
+If auto-run is **disabled**, a result's outcome (i.e. "Looks good", "Needs work", etc...) is set to "Not started" automatically if any of any of the following conditions are met:
+
+- It is newly added (defaults to the "Not Started" state).
+- A parameter in a rule is changed (only the affected rule enters the "Not Started" state).
+- The loaded project changes (all rules are be set to "Not started").
+
+#### 3. Auto-run enabled
+
+If auto-run is **enabled**, any rules that enter the "Not started" state due to the conditions listed above are immediately and automatically re-run with their results updated.
 
 ### Loading/Importing/Exporting Checklists
 
-1. User can open pre-built rubrics from the home page
+#### 1. Pre-built Rubrics
 
-- Will ask for overwrite confirmation if the user already has an in-progress checklist.
+There are pre-built rubrics are available from on home page. If a selected checklist is already in-progress, an overwrite confirmation prompt is given.
 
 ![Pre-built rubrics](/static/teachertool/prebuilt-rubrics.png)
 
-2. User can export a checklist from the vertical "..." menu near the "auto-run" button. This will download a json file.
-
+#### 2. Export a checklist
+
+A checklist is exported using the vertical "..." menu near the "auto-run" button.
+
 ![Export checklist](/static/teachertool/export-checklist.png)
 
+This will download a json file for the checklist.
+
 ![Checklist download](/static/teachertool/checklist-download.png)
 
-3. User can import a rubric from a file using the same "..." menu, or from the card on the welcome page.
+#### 3. Import a checklist
 
-- Rubric file can be selected via "Browse" or dropped directly into the popup
-- Will ask for overwrite confirmation if the user already has an in-progress checklist.
+User can import a rubric from a file using the same "..." menu, or from the card on the welcome page.
 
 ![Import checklist card](/static/teachertool/import-checklist-card.png)
 
 ![Import checklist menu](/static/teachertool/import-checklist-menu.png)
 
+Rubric file is selected using "Browse" or dropped directly into the popup. An overwrite confirmation prompted if there is currently an in-progress checklist.
+
 ![Import checklist drag in](/static/teachertool/import-checklist-dragdrop-1.png)
 
 ![Import checklist drop off](/static/teachertool/import-checklist-dragdrop-2.png)
 
 ### Other
 
-- If user refreshes the page (or closes/re-opens the browser), their checklist should be preserved.
-- User can click the print button to create a version of the results with the outcome and feedback visible, but other UI elements hidden (currently broken).
+If the page is refreshed (or if the browser closes/re-opens), the current checklist preserved.
+
+Use the print button to create a version of the results with the outcomes and feedback visible (the other UI elements are hidden).
 
 ![Print button](/static/teachertool/print-button.png)
 
-- The checklist-view/project-view splitter can be resized. It can also be reset to 50/50 split with double-click.
+The checklist-view/project-view splitter can be resized. It can also be reset to 50/50 split with double-click.
 
 ![View splitter button](/static/teachertool/view-splitter.png)
 
+Slide the splitter to widen the view of the criteria and results.
+
 ![Split view resize](/static/teachertool/split-resize.png)