diff --git a/docs/teacher/guides/faq.md b/docs/teacher/guides/faq.md index ff4d239ff..af96ba004 100644 --- a/docs/teacher/guides/faq.md +++ b/docs/teacher/guides/faq.md @@ -10,6 +10,8 @@ Students and users are given access to a module using their college email addres 4. Enter the enrolment page by clicking the **Entroll Students :material-plus:** button 5. Enroll students by supplying one or more student email addresses +For a visual guide, click [here](./gettingstarted.md#enrolling-students) + ## How can I move questions between problem sets? When creating a new question the teacher can choose to "clone" from an existing question. The teacher can then delete the original version. diff --git a/docs/teacher/guides/gettingstarted.md b/docs/teacher/guides/gettingstarted.md index f28c12875..0354af6be 100644 --- a/docs/teacher/guides/gettingstarted.md +++ b/docs/teacher/guides/gettingstarted.md @@ -64,11 +64,11 @@ In **Teacher mode**, open your module's home page, click the 'Students' tab, and Enter a student's email address, or alternatively paste in a list of email addresses separated by commas. -![Add_student_before](./images/Add_student_before.png) +![Add_student_before](./images/Add_student_before.png){: style="width:200px"} Press 'Enter' to add the email addresses: -![Add_student_after](./images/Add_student_after.png) +![Add_student_after](./images/Add_student_after.png){: style="width:200px"} Then click 'SUBMIT' to enrol the students. diff --git a/docs/teacher/guides/good-practice.md b/docs/teacher/guides/good-practice.md index e51878b99..e9feb9ece 100644 --- a/docs/teacher/guides/good-practice.md +++ b/docs/teacher/guides/good-practice.md @@ -1,78 +1,101 @@ # Good practice -## Romanised operators +## Formatting & style for readability -Use romanised operators such as $\sin$, $\frac{\mathrm{d}}{\mathrm{d}x}$ instead of $sin$, $\frac{d}{dx}$, etc. +### Use romanised text for operators and units -## Use empty lines +Use romanised operators and scientific units to distinguish them from variables, which are italicised. -Using empty lines can improve the readability and neatness of your content. Empty lines are often useful before and after an equation, and between paragraphs of text. An empty line in markdown requires _two spaces_ on the line, otherwise the line is ignored. +* **Operators:** Use `\sin`, `\cos`, `\log`, `\det`, etc. For derivatives, use `\mathrm{d}` as in `\dfrac{\mathrm{d}y}{\mathrm{d}x}`. + * **Correct:** $\sin(x)$, $\dfrac{\mathrm{d}}{\mathrm{d}x}$ + * **Incorrect:** $sin(x)$, $\frac{d}{dx}$ -## Space between numbers and units +* **Units:** Use `\text{...}` or `\mathrm{...}` (mathrm allows for numbers in the units, i.e. $\mathrm{m^2}$). Ensure the unit's case is correct (e.g., `m` for milli, `M` for mega). + * **Correct:** $5 \text{ m}$, $10 \text{ kN}$ + * **Incorrect:** $5 m$, $10 kN$ + +### Space between numbers and units Put appropriate space between a number and its unit, such as `5 m` or `3 kg`, according to the SI conventions. -## Romanise units and check their case +e.g. `$5 \text{ m}$` to get $5 \text{ m}$ -Use romanised units such as $\text{m}$, $\text{kN}$ instead of $m$, $kN$. Ensure that the case of the unit is correct. +### Use empty lines -## Add tests to response areas +Using empty lines can improve the readability and neatness of your content. -In a response area, press `configure` then `tests`. +Empty lines are often useful before and after an equation, and between paragraphs of text. An empty line in markdown requires _two spaces_ on the line, otherwise the line is ignored. -Tests allow you to enter potential student responses, define whether they are correct or not, then run the evaluation function on those student responses. This allows you to quickly test whether or not the evaluation function works as expected. +Alternatively, adding empty LaTeX text, `\text{}`, can work if all else fails. -## Save and publish as you go +## Using platform features effectively -Saving and publishing work regularly is recommended to prevent accidental data loss. +### Save and publish as you go -## Use branching when relevant +Saving and publishing work regularly is recommended to prevent accidental data loss. -Branching is a feature for `worked solutions`. It allows you to have different solution pathways Usage examples: +### Add tests to response areas -- When a question can be solved via multiple different methods, branching can be used for each method. -- When a question has multiple parts, where each part involves substitution of different values, branching can be used for each part. +In a response area, press `Configure` then `Test`. -![gif showing the branching feature](images/branching.gif) +Tests allow you to enter potential student responses, define whether they are correct or not, then run the evaluation function on those student responses. This allows you to quickly test whether or not the evaluation function works as expected. -## Use pre-response area text to be clear what should be entered +### Use pre-response area text to be clear what should be entered -Pre-response area text is found under `configure` - `INPUT` in the evaluation function. +Pre-response area text is found under `Configure` - `Input` in the evaluation function. You can use LaTeX in the pre-response area text. ![Image showing a pre-response area](images/pre_response_area.png) -## Use `\dfrac` for bigger fractions when needed. +### Use live preview and permit all types of input -Use `$\dfrac{numerator}{denominator}$` for bigger fractions when you need to display them more clearly or emphasize them. For example, `$\dfrac{3}{4}$` will produce a bigger fraction than `$\frac{3}{4}$`. -Alternatively, you can use `$\displaystyle$` at the start of an inline equation to render everything afterwards full-size (as in display maths mode), this is especially helpful for integrals. +Live preview is found under `Configure` - `Input` - `Display settings`. -## Use `\small` when smaller fonts or fractions are needed +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. -Use `$\small{text}$` when you need to display smaller fonts or fractions in your LaTeX expressions. For example, `$\small{\frac{1}{2}}$` will produce a smaller fraction than `$\frac{1}{2}$`. +![Image showing a live-preview to a student's response](images/live_preview.png) -## Use audio clips +### Use branching when relevant -Just drag + drop an audio file into the milkdown editor. +Branching is a feature for `worked solutions`. It allows you to have different solution pathways Usage examples: -## Issue with input symbols +- When a question can be solved via multiple different methods, branching can be used for each method. +- When a question has multiple parts, where each part involves substitution of different values, branching can be used for each part. -For the `code` of input symbols in the response areas, the system cannot accept brackets (i.e `dot(x)` for $\dot{x}$) and response must be formatted in different ways (i.e `dot_x`). +![gif showing the branching feature](images/branching.gif) -`a_b` will render as $a_b$ without adding an input symbol, but note that `dot_x` overrides the `_` input (in this example, will render as $\dot{x}$ instead of $dot_x$) +### Use audio clips -## Use live preview and permit all types of input +Just drag + drop an audio file into the editor. -Live preview and input types are found in an evaluation function under `configure` - `INPUT`. +### Issue with input symbols -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. +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`). -![Image showing a live-preview to a student's response](images/live_preview.png) +`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 -1. Use `\begin{array}` to generate a compact table i.e. +### Use `\dfrac` for bigger fractions when needed. + +Use `$\dfrac{numerator}{denominator}$` for bigger fractions when you need to display them more clearly or emphasize them. For example, `$\dfrac{3}{4}$` will produce a bigger fraction than `$\frac{3}{4}$`: + +$\dfrac{3}{4} \quad$ (dfrac) + +$\frac{3}{4} \quad$ (frac) + +Alternatively, you can use `$\displaystyle$` at the start of an inline equation to render everything afterwards full-size (as in display maths mode), this is especially helpful for integrals. + +### Use `\small` when smaller fonts or fractions are needed + +Use `$\small{text}$` when you need to display smaller fonts or fractions in your LaTeX expressions. For example, `$\small{\frac{1}{2}}$` will produce a smaller fraction than `$\frac{1}{2}$`. + +$\small{\frac{1}{2}} \quad$ (small) + +$\frac{1}{2}$ + +### Use `\begin{array}` to generate a compact table i.e. ```latex \begin{array}{|c|c|} @@ -88,7 +111,7 @@ Live preview instantly renders a student's input. This is very useful for long/c ![Image showing a example of a table](images/table.png) -2. Use `\begin{aligned}` to keep your working formatted nicely +### Use `\begin{aligned}` to keep your working formatted nicely ```latex \begin{aligned} @@ -100,7 +123,7 @@ Live preview instantly renders a student's input. This is very useful for long/c ![Image showing a example of a algined working](images/aligned.png) -3. Use `\left` and `\right` for equations with multiple brackets +### Use `\left` and `\right` for equations with multiple brackets ```latex f(x)=\left (\frac{(\cos (x) -x) + i(\sin (x) - x)}{wi} \right) @@ -110,4 +133,6 @@ Live preview instantly renders a student's input. This is very useful for long/c This also works for `[ ]` and `\{ \}` -4. Use `\sin`, `\cos`, etc. as a shortcut for `\text{sin }`, `\text{cos }`, etc. +### Shortcut for romanised operators + +Use `\sin`, `\cos`, etc. as a shortcut for `\text{sin }`, `\text{cos }`, etc. diff --git a/docs/teacher/guides/images/Add_student_after.png b/docs/teacher/guides/images/Add_student_after.png index 10cf80d79..8e1a24e03 100644 Binary files a/docs/teacher/guides/images/Add_student_after.png and b/docs/teacher/guides/images/Add_student_after.png differ