Instances, lexdown, access

Peter Johnson · Peter Johnson · commit 14e1f409760c · 2025-07-10T22:45:38.000+01:00
diff --git a/docs/student/lexdown_student.md b/docs/student/lexdown_student.md
@@ -22,7 +22,7 @@ Produces the following output:
 
 \[ \int_V \nabla \cdot \vec{f} \mathrm{d}V = \oint_S \vec{f} \cdot \hat{n} \mathrm{d}S \]
 
-In the Milkdown editor, anything surrounded by dollar signs (like `$ x^2 $`) will be interpreted as LaTeX. 
+In the Lexdown editor, anything surrounded by dollar signs (like `$ x^2 $`) will be interpreted as LaTeX. 
 Only the subset supported by [KaTeX](https://katex.org/docs/supported), which includes most common LaTeX functions, can be used.
 
 ### LaTeX equations in 5 minutes
diff --git a/docs/teacher/guides/analytics.md b/docs/teacher/guides/analytics.md
@@ -1,21 +1,23 @@
 # Analytics Guide
 
-Analytics begin when a question is _published_. After publishing a question for the first time it becomes available to students and their usage is logged and fed back to the student and the teacher. 
+## Module-level analytics
+
+The module overview tab displays cohort progress and cohort activity. Access to the overview tab is subject to teacher role privileges.
+
+The Content tab displays all Sets, with cohort-level data on activity and progress within each Set. Access to the data within the Content tab is subject to teacher role privileges.
 
-## Analytics History
+Within the content there is a stats tab which shows cohort-level data on question completion and statistics on time spent on each question. Response Areas are listed and show completion rates overall, and best per student. Detailed response statistics are available in the 'Explore' button on the Response area. The stats tab availability is subject to teacher role privileges.
 
-Analytics are linked to response areas. Each question can have more response areas and they can be added or removed. When a response area is removed, then it is removed only from the "current version" of the question (the version that the teacher is editing) and it persists on the previous version(s) of the question. It means that all submissions and analytics remain, but they are now linked to the response area which only exists on a previous version(s) of the question.
+The ID of Response Areas is linked between module instances. If a Response Area maintains the response data shape then the data across multiple instances can be combined for stronger statistics. As of 10/7/25 there are no features in the UI to link data across instances, but these links will be added in future (the data saved is in the correct structure to allow this feature on all past data).
+
+## Analytics and question versions
+
+Analytics begin when a question is _published_. After publishing a question for the first time it becomes available to students and their usage is logged and fed back to the student and the teacher. 
 
-Currently it is possible to see only analytics against the published version of the question.
+Each question can have add or remove response areas. When a response area is removed, then it is removed only from the "current version" of the question (the version that the teacher is editing) and it persists on the previous version(s) of the question. This means that all submissions and analytics remain, but they are now linked to the response area which only exists on a previous version(s) of the question.
 
-We are now working on the improvement so that it is possible to see analytics against all reponse areas (including those that exist only on previous versions of the question).
+Currently (as of 10/7/25) only analytics against the published version of the question can be seen in the UI. Other data, although still saved, cannot be seen.
 
-## Tracking students' response
-To improve the feedback that students receive and to better understand which areas they need help with, it is possible to check the different student responses and the frequency of each response for each response area. 
 
-To see these statistics:
 
-1. Click on the **Stats** tab in teacher mode.
-2. Then click on **Explore** in the top right corner of each response area.
 
-You can even export these statistics as csv file!
diff --git a/docs/teacher/guides/content-sets-questions.md b/docs/teacher/guides/content-sets-questions.md
@@ -13,7 +13,7 @@ This guide explains how to use the editor to create and modify [sets](https://la
 | **1** | **Add Question** | Add a new blank question, duplicate an existing question, or upload a .zip file containing one or more question JSON files. |
 | **2** | **File, Preview, and Stats** | Access pages for:<br>• **File:** Manage versions, download as a JSON file, or delete the question.<br>• **Preview:** See the question as a student would.<br>• **Stats:** View statistics on student responses for the question. |
 | **3** | **Question Name** | Edit the name of the question. |
-| **4** | **Master Content** | The main content for the question, which is always visible above the individual parts. This field uses the Milkdown editor. |
+| **4** | **Master Content** | The main content for the question, which is always visible above the individual parts. This field uses the Lexdown editor. |
 | **5** | **Current Part** | **Indicates** which question part you are currently editing. |
 | **6** | **Part Content** | Edit the content for the selected question part (i.e., the sub-question). |
 | **7** | **Response Area** | The input field where a student submits their answer. Adding a response area is optional. |
diff --git a/docs/teacher/guides/gettingstarted.md b/docs/teacher/guides/gettingstarted.md
@@ -99,3 +99,9 @@ first.nameYY@ic.ac.uk
 <br>
 
 This is because we use Azure Active Directory (i.e., Microsoft) to **authorise** users.
+
+## Enrolling Teachers
+
+Teachers with the 'enrol teachers' privilege on a particular module instance can enrol other teachers on that instance. The process is similar to enrolling students as above, but in the 'Teachers' tab. When enrolling a teacher on a module instance, a role can be selected, and the privileges for that role are listed. 
+
+Teachers without the 'enrol teachers' privilage on a particular module instance, if attempting to enrol teachers, will not be able to access the feature but will receive feedback accordingly. 
diff --git a/docs/teacher/guides/good-practice.md b/docs/teacher/guides/good-practice.md
@@ -52,9 +52,9 @@ You can use LaTeX in the pre-response area text.
 
 ### Live preview
 
-Live preview instantly renders a student's input. This is very useful for long/complicated equations, as it allows students to ensure their input is correct.
+Live preview is on by default with the Expression response area. Live preview instantly renders a student's input. This is very useful for long/complicated equations, as it allows students to ensure their input is correct.
 
-Live preview is found under `Configure` - `Input` - `Display settings`.
+Live preview settings are found under `Configure` - `Input` - `Display settings`.
 
 ![Image showing a live-preview to a student's response](images/live_preview.png)
 
@@ -71,13 +71,20 @@ Usage examples:
 
 ### Audio clips
 
-Just drag + drop an audio file into the editor.
+Drag + drop an audio file into the editor, or record audio on the 'Insert v' drowpdown in Lexdown.
 
-### Issue with input symbols
+### Input symbols
+
+Input symbols help in two ways:
+
+1. Show the evaluation function how to interpret responses
+2. (If displayed) show the student how to express their response
+
+Input symbols require a display symbol where single dollars to delimit inline-math latex are recommended (e.g. `$x$` will display to students as $x$) and corresponding code to be used by the evaluation function (e.g. `x`). Displaying symbols to students is helpful when it's not clear how to type a symbol as code; for exaxmple symbol $\rho$ may be inserted is `rho` or `r` or `p` depending on the opinion of the teacher.
+
+Providing alternatives is optional but recommended. Alternatives help provide higher reliability feedback. For example, alternatives to `rho` could be `Rho`, `RHO`, `r`, `R`, `p`, `P` - although some of these may not be acceptable if they have another meaning in the context in question. 
 
-When defining the `code` of an input symbol in the response areas, the system cannot accept brackets (i.e using `dot(x)` for $\dot{x}$). The response must be formatted in a different way (i.e `dot_x`). 
 
-`a_b` will render as $a_b$ without adding an input symbol, but note that `dot_x` will override the `_` input in this example (will render as $\dot{x}$ instead of $dot_x$).
 
 ## Latex help
 
diff --git a/docs/teacher/guides/lexdown.md b/docs/teacher/guides/lexdown.md
@@ -9,7 +9,7 @@ The lexdown is widely used in Lambda Feedback. It accepts:
 
 The lexdown editor is an adapted version of lexical to use markdown-first, and incorporate features including drag-and-drop images, embedded videos and autio, and switch to raw markdown.
 
-## Common needs in milkdown
+## Common needs in Lexdown
 
 Here's a walkthrough to create some basic content:
 
diff --git a/docs/teacher/reference/content_management.md b/docs/teacher/reference/content_management.md
@@ -1,12 +1,47 @@
-# Access control
+# Content structure
 
 ## Modules
 
-Module access for students is controlled by enrolling student users. More details to be added here.
+Modules are the fundamental unit of content management in Lambda Feedback (not, for example, cohorts, or years/terms/semesters)
+
+## Instances of a module (e.g. '2026/27')
+
+Instances of a module are independentent but share the same umbrella title to help organise content. A module with multiple instances will have a drop-down menu in the title bar where users can switch modules. If you do not see the drop-down then you do not have access to other instances (or there are no other instances).
+
+![screenshot showing dropdown menu of multiple instances](../images/switch_instance_teacher.png)
+
+### Default instance when there are multiple
+
+When opening a module in Lambda Feedback the default instance opens. The default is defined based on start and end dates for the instances. There are obvious cases such is if there is only one instance, or only one instance that is open and not closed. Logic for other cases is as follows:
+
+| Case | Default instance|
+|---|---|
+|All instances closed in past|Most recent start date|
+|All instances not started yet|Latest start date*|
+|Multiple instances open|Latest start date|
+
+
+\* This logic seems incorrect, but as of 10/7/25 it was the behaviour of the system
+
+The UX is based around the default being the most common need. In the rare case that access to a different instance is required, navigation is available.
+
+Note that students rarely access multiple instances of a module; teachers rarely access previous/closed instances of a module. 
+
+### Data continuity between instances
+
+Instances are independent. New instances are created without students enrolled, submissions or events recorded, or comments. Student and teacher enrollments are independent between different instances.
+
+## Teacher roles
+
+There are multiple Teacher roles, which are allocated per module instance. Admins manage the list of teacher roles available within a tenant. Each teacher role has a customised combination of privileges. One role always exists, which is 'Module Owner', which includes all privileges. 
+
+## Enrolment
+
+Access for students or teachers is controlled by enrollment, which is detailed in the [getting started](../guides/gettingstarted.md#enrolling-students) guide. 
 
 ## Sets
 
-Set access is granted to all users enrolled on a module, but the Set can be hidden by the teacher. Two methods can be used to hide a Set:
+Set access is granted to all student users enrolled on a module instance, but the Set can be hidden by the teacher. Two methods can be used to hide a Set:
 
 1. Start and end dates (both optional) can be created in the Set Metadata.
 2. The Set can me _manually hidden_, which overrides the above settings.
@@ -15,7 +50,7 @@ Set access is granted to all users enrolled on a module, but the Set can be hidd
 
 The following types of support materials are available to students in the `help` section:
 
-- Sructured tutorial
+- Structured tutorial
 - Final answer
 - Worked solutions
 
diff --git a/docs/teacher/reference/images/switch_instance_teacher.png b/docs/teacher/reference/images/switch_instance_teacher.png
diff --git a/docs/teacher/reference/latex_functionality.md b/docs/teacher/reference/latex_functionality.md
@@ -8,9 +8,9 @@ All content is formatted in [_markdown_](https://www.markdownguide.org/basic-syn
 
 Special attention is required when formatting $\LaTeX$ which, although it is formatted using standard markdown (i.e. delimited by the `$` for 'inline formulas', and `$$` for an equation environment), must use a subset of $\LaTeX$ in order to compile for both outputs. This sometimes requires a compromise by the author.
 
-## The milkdown editor
+## The Lexdown editor
 
-All content in Lambda Feedback is stored as markdown (ASCII content), however it is always input/edited using the [milkdown](https://milkdown.dev/online-demo) editor. This editor has the advantage of providing live interactive previews of content, including $\LaTeX$ via katex.
+All content in Lambda Feedback is stored as markdown (ASCII content), input/edited using our Lexdown editor. The editor has a preview mode providing live interactive previews of content, including $\LaTeX$ via katex, and a raw markdown mode.
 
 ## Web requirements: katex
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -36,15 +36,15 @@ nav:
           - Getting Started: "teacher/guides/gettingstarted.md"
           - Editing questions: "teacher/guides/content-sets-questions.md"
           - Exporting and importing questions: "teacher/guides/question-export-import.md"
-          - Milkdown: "teacher/guides/lexdown.md"
+          - Lexdown: "teacher/guides/lexdown.md"
           - Analytics: "teacher/guides/analytics.md"
           - Good practice: "teacher/guides/good-practice.md"
           - FAQ: "teacher/guides/faq.md"
           - Guidance:
               - Guidance Time Suggestion: "teacher/guides/guidance/guidance-time-suggestion.md"
 
       - Reference:
-          - Access control: "teacher/reference/access_control.md"
+          - Content management: "teacher/reference/content_management.md"
           - Latex functionality: "teacher/reference/latex_functionality.md"
           - PDF generation: "teacher/reference/pdf_generation.md"
           - Response Areas:
