Update index.md

Author: CarkHT

docs/teacher/reference/response_area_components/index.md

@@ -84,82 +84,77 @@ This is a 'no code' parametric configuration. Settings will be upgraded as the s
 - **Evaluation Function Parameters** - Configure as provided, and add new parameters as required. Details depend on the selected Evaluation Function.
 -   **Input Symbols:** This is a powerful feature for defining a dictionary of accepted symbols. For each symbol, you define:
     *   **Symbol:** The LaTeX-rendered symbol (e.g., `$f(x)$`).
-    *   **Code:** The machine-readable variable name (e.g., `fx`). This is what you use in your reference answer and what the evaluation function sees.
+    *   **Code:** The machine-readable variable name (e.g., `fx`). This is what your students will type and what the evaluation function sees.
     *   **Alternatives:** A list of other codes you want to accept for the same symbol (e.g., `f_x`, `f(x)`, `f`). This allows you to anticipate different ways students might type the same thing.
     *   **Visibility:** A `TRUE`/`FALSE` toggle. If "Display input symbols" is enabled in the Input tab, this setting determines whether a specific symbol is shown to the student. This allows you to show students common symbols while still accepting less common or alternative ones in the background.
 
-- **Input Symbols** - Define a dictionary of symbols and their equivalent in code form.
-    - This essentially associates a LaTeX-rendered symbol with a machine-readable variable label, with the LaTeX render returned to the student through the preview. These symbols may also be hidden to students.
-    - All inputs are plain text. For example, the symbol `$f(x)$` may have code `fx` and alternatives `f_x`, `f(x)`, `f`. This dictionary will be provided to the evaluation function, even if the teacher has not displayed it to the student. This allow teachers to accept several alternative symbols, such as those with different cases or conventional expressions.
-    - The configuration of input symbols is a very important part of providing high quality feedback.
-    - Note that the 'visibility' Boolean applies if input symbols are displayed to students, otherwise it is irrelevant. It allows Teachers to communicate some symbols to students, while keeping others hidden to the student but visible to the evaluation function.
-
 ### 3. FEEDBACK
 
-Add alternative reference answers, 'cases', with customised parameters, so that multiple cases can be dealt with independently. Cases can be used to capture multiple correct approaches that are not equivalent. Cases can also be used to identify common incorrect approaches and to provide customised feedback. The FEEDBACK tab is typically populated after students start using the system, and when data is available to point to common expressions. Configuring a case works similarly to setting up the default answer in the INPUT tab, with added options for changing the colour of the given feedback, give custom feedback and toggling whether the case answer should be considered correct or not. Adding custom feedback will overwrite the feedback produced by the evaluation function. When a response is submitted, it is evaluated for all cases and feedback for the first case that matches will be displayed. When determining which matched case is first, the default answer described in the INPUT tab will take precedence over all other cases, otherwise the feedback for the matched case with the lowest number will be displayed (i.e. the answer given in the INPUT tab can be considered to be Case 0). <br> Feedback fields also support LaTeX equations in both `$f(x)$` and `$$f(x)$$` formats, and Markdown inputs such as line breaks. Make sure to follow good typesetting practice in this field.
+Here, you can go beyond a simple "correct/incorrect" and provide nuanced feedback by creating **"cases."**
+
+Cases are an alternative answer you want to check for. You can use cases to:
+*   Award full marks for a different but equally valid answer.
+*   Identify a common mistake and provide specific, tailored feedback to help the student learn.
+
+For each case, you can:
+*   Enter an alternative answer to check for.
+*   Specify if the case should be marked as "correct" or "incorrect."
+*   Write custom feedback text that overrides the default feedback from the evaluation function.
+*   Change the color of the feedback (e.g., green for correct, orange for a hint).
+
+Teachers typically add cases after students start submitting answers, and data about common student answers is created.
+
+When a student submits a response, it's evaluated against all cases. The system displays feedback for the **first case that matches**. The main answer you set in the 'Input' tab is treated as "Case 0" and is always checked first.
+
+Feedback fields also support LaTeX equations in both `$f(x)$` and `$$f(x)$$` formats, and Markdown inputs such as line breaks. Make sure to follow good typesetting practice in this field.
 
 ![Screenshot](screenshots/Feedback.gif)
 
 ### 4. TEST
 
-tests provide a systematic way to log what behaviour the teacher expects. It provides a useful record and an efficient way to retest the bevhaiour of a response area over time (e.g. as evaluation functions evolve, or as the subject matter itself changes).
-
-## Restrictions on changes: the input type
+Tests provide a systematic way to log what behaviour the teacher expects. You can create a list of test inputs and define the expected outcome for each.
 
-It is possible to change the input type (e.g. from _Text_ to _Number_) without any restrictions until the response area is saved (with or without publishing) to students.
+It provides a useful record and an efficient way to retest the bevhaiour of a response area over time (e.g. as evaluation functions evolve, or as the subject matter itself changes).
 
-After the response area is saved, it is still possible to change the input type, but it will result into replacing the response area by a new one. The previous response area will still exist, but only on the previous version of the question. When replacing the response area, all response area content data (those entered by teachers including tutorials, final answer and worked solutions) are copied, but any existing response area event data (student answers, click events and statistics) will remain linked only to the previous response area.
+## Restrictions on changing the input type
 
-Student answers, click events and statisticsthose data are never lost by deleting a response area, they are always preserved. Once a question is saved (with or without publishing), then any new changes are saved into a new (draft) version of the question. So, if e.g. a response area is deleted after a question was published, then it is deleted from the draft version only. And if this draft version is later published, then the previously published version is preserved (and with it the "deleted" response area and linked submissions).
+It is possible to change the input type (e.g. from _Text_ to _Number_) without any restrictions until the response area is saved.
 
-The reason why the input type change is restricted is to preserve high quality data analytics as explained in the examples below.
+After the response area is saved, it is still possible to change the input type, but it will result into replacing the response area by a new one. The previous response area will still exist, but only on the previous version of the question. When replacing the response area, all content (e.g. answers, feedback cases) is preserved, but any existing student submissions and analytics will remain linked only to the previous response area.
 
-### An Example 1 - changing input type on PUBLISHED response area
+Student answers, click events and statistics are never lost by deleting a response area. Once a question is saved (with or without publishing), then any new changes are saved into a new (draft) version of the question. So, if e.g. a response area is deleted after a question was published, then it is deleted from the draft version only. And if this draft version is later published, then the previously published version is preserved (and with it the "deleted" response area and linked submissions).
 
-#### FIRST Part
-- The teacher creates a new question with Response Areas RA1 and RA2. -> The version of the question is QV1 with status DRAFT.
-- The teacher is making changes (including the change of the input type if needed). -> The changes are being saved into QV1 with no restrictions
-- The teacher performs PUBLISH action (let's assume RA1 and RA2 input types are both _Number_ for this example). -> The QV1 version status is changed to PUBLISHED
-- Students are submitting their answers -> submissions are recorder against Response Area RA1 and RA2 (in the single _Number_ format for both response areas)
-- The teacher clicks on a question to edit it -> with the first click a new question version QV2 is created with status DRAFT
-- The teacher makes following changes (which are being recorded against QV2):
-    - In RA1: adds a new Input Symbol -> the change is recorded against RA1
-    - In RA2: the teacher unlocks and changes the input type -> RA2 is deleted (from the question version QV2) and a new response area RA3 is created (let's assume input type _Table_ for this example)
-- The teacher performs PUBLISH action -> the QV2 is published (with response area RA1 with input type _Number_ and response area RA3 with input type _Table_)
-- Students are submitting their answers -> submissions are recorder against Response Area RA1 (in the single _Number_ format) and against Response Area RA3 (in the _Table_ format)
+The reason why the input type change is restricted is to preserve high quality data analytics as explained in the examples below.
 
-  => No submissions are lost. The original submissions (in the _Number_ format) are linked to the RA2, which is preserved on the question version QV1. New submissions (in the _table_ format) are linked to the RA3 which is recorded on the question version QV2.
+### Example 1 - changing input type on PUBLISHED response area
 
-**Please note:** All statistics and submissions are currently displayed against the published question version only. So, though the submissions against RA2 are preserved, it is not currently possible to see them. We are working on the improvement to make this possible.
+1.  **Create and Publish:** You create a question with "Response Area 1" and "Response Area 2," both using the *Number* input type. You **Publish** the question. Let's call this `Version 1`.
+2.  **Students Submit Answers:** Students begin submitting answers, which are recorded for both response areas.
+3.  **Edit the Question:** You decide to edit the question. The system automatically creates a new draft, `Version 2`.
+4.  **Make Changes:**
+    *   In "Response Area 1," you add a new input symbol. This is a simple change and doesn't affect the input type.
+    *   In "Response Area 2," you change the input type from *Number* to *Table*.
+5.  **The Result:** Because `Version 1` was published, changing the input type triggers the replacement process. The original "Response Area 2" is archived (with its student data) in `Version 1`. A brand new "Response Area 3" (with the *Table* input type) is created in its place in `Version 2`.
+6.  **Publish Again:** You publish `Version 2`.
 
-#### SECOND Part - this is an extension of the FIRST Part
-- The teacher decides to REVERT (the question created in the FIRST Part) to the question version QV1 -> a new question version QV3 is created and the content of the QV1 is copied to QV3 -> QV3 is DRAFT version which contains RA1 (input type _Number_) and RA2 (input type _Number_)
-- The teacher performs PUBLISH action -> the QV3 is published and the teacher can now see submissions against RA1 and RA2, but he cannot see anymore submissions against RA3 (these are preserved against the QV2 version)
+**The Takeaway:**
+*   New student submissions will be recorded for "Response Area 1" (*Number*) and "Response Area 3" (*Table*).
+*   The original submissions to "Response Area 2" are safe and preserved with `Version 1`, but you won't see them in the analytics for the currently published `Version 2`.
+*   If you later **Revert** to `Version 1`, you will once again see the analytics for "Response Area 1" and the original "Response Area 2".
 
+**Please note:** All statistics and submissions are currently displayed against the published question version only. So, though the submissions against "Response Area 2" are preserved, it is not currently possible to see them. We are working on the improvement to make this possible.
 
-### An Example 2 - changing input type on SAVED response area
+### Example 2 - changing input type on SAVED response area
 
-- The teacher creates a new question with Response Areas RA1 and RA2. -> The version of the question is QV1 with status DRAFT.
-- The teacher is making changes (including the change of the input type if needed). -> The changes are being saved into QV1 with no restrictions
-- The teacher performs SAVE action (let's assume RA1 and RA2 input types are both _Number_ for this example). -> The QV1 version status is changed to SAVED
-- The teacher clicks on a question to edit it -> with the first click a new question version QV2 is created with status DRAFT
-- The teacher makes following changes (which are being recorded against QV2):
-    - In RA1: adds a new Input Symbol -> the change is recorded against RA1
-    - In RA2: the teacher unlocks and changes the input type -> RA2 is deleted (from the question version QV2) and a new response area RA3 is created (let's assume input type _Table_ for this example)
-- The teacher performs PUBLISH action -> the QV2 is published (with response area RA1 with input type _Number_ and response area RA3 with input type _Table_)
-- Students are submitting their answers -> submissions are recorder against Response Area RA1 (in the single _Number_ format) and against Response Area RA3 (in the _Table_ format)
-- The teacher decides to REVERT to the question version QV1 -> a new question version QV3 is created and the content of the QV1 is copied to QV3 -> QV3 is DRAFT version which contains RA1 (input type _Number_) and RA2 (input type _Number_)
-- The teacher performs PUBLISH action -> the QV3 is published and the teacher can now see submissions against RA1. There are no submissions against RA2 as it has not been (until now) published. Submissions against RA3 are not visible, but they are preserved against the question version QV2.
+This scenario works almost identically to the one above. The key is that once a question version is **Saved**, the input types of its response areas are locked to protect potential future analytics. If you edit a saved question and change an input type, it will still trigger the replacement process (archiving the old and creating a new response area).
 
-### An Example 3 - adding new response area to a published question
+### Example 3 - adding new response area to a published question
 
-- The teacher creates a new question with Response Areas RA1 and RA2. -> The version of the question is QV1 with status DRAFT.
-- The teacher is making changes (including the change of the input type if needed). -> The changes are being saved into QV1 with no restrictions
-- The teacher performs SAVE (or PUBLISH) action (let's assume RA1 and RA2 input types are both _Number_ for this example). -> The QV1 version status is changed to SAVE (or PUBLISHED)
-- The teacher clicks on a question to edit it -> with the first click a new question version QV2 is created with status DRAFT
-- The teacher adds a new response area RA3
+1.  **Start with a Published Question:** You have a published question (`Version 1`) with "Response Area 1" and "Response Area 2."
+2.  **Edit the Question:** You start editing, which creates a new draft (`Version 2`).
+3.  **Add a New Response Area:** You add "Response Area 3."
 
-  => At this point the teacher is making changes in the question version QV2 (DRAFT) in which:
+**The State of `Version 2` (Draft):**
+*   The input types for "Response Area 1" and "Response Area 2" are **locked**. This is because they exist on a previously saved version (`Version 1`). To change their type, you must go through the replacement process described above.
+*   The input type for the new "Response Area 3" is **unlocked**. You can change it freely because it doesn't exist on any previously saved version and has no associated student data to protect. It will only become locked after you Save or Publish `Version 2`.
 
-    - The input types of RA1 and RA2 are locked, because they exist on a saved version QV1. It does not matter if QV1 is (only) saved or published or if there are  or there are not existing submissions. The reason why it is locked is that the teacher can revert into this version later after submissions are created. By locking it we are making sure that the "unlock" process will be triggered which will preserve the original response area and it will create a new response area and it will make sure that the submissions are linked to response area with compatible input type.
-    - The input type of RA3 is not locked at this point, because RA3 does not (yet) exist on any saved question version.