From 84dc7ea4d763e3f72569943e35be2976311121e3 Mon Sep 17 00:00:00 2001 From: ganicke Date: Mon, 19 Aug 2024 16:07:22 -0700 Subject: [PATCH] do some revisions to the features text --- docs/teachertool.md | 124 +++++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 49 deletions(-) diff --git a/docs/teachertool.md b/docs/teachertool.md index 958592f349e..31aa47b4983 100644 --- a/docs/teachertool.md +++ b/docs/teachertool.md @@ -2,17 +2,17 @@ ## 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) @@ -20,62 +20,70 @@ A user can create a new rubric using the "New Rubric" card (or from the "..." ac #### 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) @@ -83,62 +91,80 @@ User can fill in parameters: ![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)