Documentation feedback and improvements

en/faq/activities/index.md

@@ -13,3 +13,14 @@ On the home page of Dodona, you can find all your drafts under _Draft exercises_
 
 ## How do I create new exercises? <Badge type="tip" text="teacher" />
 As a teacher, you can use the hundreds of exercises that are available in Dodona, but you can also create new exercises yourself. You can follow [this guide](/en/guides/exercises/creating-exercises/introduction) for this.
+
+## What is the difference between a course and a repository? <Badge type="tip" text="teacher" />
+In Dodona, an "exercises repository" is a collection of exercises and reading activities managed in a linked GitHub repository.
+These exercises can then be used in multiple "courses".
+
+A "course" in Dodona is again a collection of exercises and reading activities structured in sequences.
+Here you can, for example, structure exercises according to a desired learning path.
+Courses are fully managed within Dodona.
+A course can contain exercises from different exercise repositories.
+A course also includes enrolled students.
+In a course, you can monitor these students, make evaluations, answer questions, etc...

en/faq/annotations/index.md

@@ -37,13 +37,13 @@ You can also respond to an existing question from yourself or to a comment from
 
 ## How do I know if my question has been answered? <Badge type="tip" text="student" />
 
-When a teacher answers your question, you will receive a notifications in Dodona. This notification will redirect you to the page where you asked the question.
+When a teacher answers your question, you will receive a notification in Dodona. This notification will redirect you to the page where you asked the question.
 
 ![image](./comment_on_code.png)
 
 ## How can I enable/disable student questions? <Badge type="tip" text="teacher" />
 
-Use the pencil in the top navigation bar of your course to go to the `edit` page. Here you can enable or disable student questions by checking or unchecking the box `Allow students to ask questions`.
+Use the pencil in the top navigation bar of your course to go to the `Edit` page. Here you can enable or disable student questions by checking or unchecking the box `Allow students to ask questions`.
 
 ![img.png](./ask_questions_toggle.png)
 
@@ -59,7 +59,7 @@ You will also see a notification in the top navigation bar of your course. Click
 
 ![img.png](./course_question_list.png)
 
-If you want to see al open question across all your courses, you can go to the `questions` page in the navigation sidebar of Dodona.
+If you want to see al open question across all your courses, you can go to the `Questions` page in the navigation sidebar of Dodona.
 
 ![img.png](./questions_index_page.png)
 
@@ -91,11 +91,11 @@ You can either use the `Add global comment` button to add a general comment abou
 
 Students often make the same mistakes, or have similar questions. To avoid having to write the same comment over and over again, you can reuse comments.
 
-While writing or editing a comment, you can check `save comment`. This will allow you to add a title for this comment, which should help you find the comment for future use.
+While writing or editing a comment, you can check `Save comment`. This will allow you to add a title for this comment, which should help you find the comment for future use.
 
 ![Save comment while writing](./save-comment-edit.png)
 
-You can also save an existing comment by clicking `save comment` in the comment menu.
+You can also save an existing comment by clicking `Save comment` in the comment menu.
 
 ![Save existing comment](save-comment.png)
 

en/guides/exercises/creating-exercises/content/index.md

@@ -0,0 +1,9 @@
+---
+title: "Creating exercises: reading activity"
+sidebarTitle: Reading activity
+order: 4
+prev: true
+next: true
+---
+
+This guide is not yet available in English.

en/guides/exercises/creating-exercises/management/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Creating exercises: next steps"
 sidebarTitle: Next steps
-order: 4
+order: 5
 prev: true
 next: false
 ---

en/references/exercise-config/index.md

@@ -30,7 +30,7 @@ Dodona allows setting the configuration of an **exercise** and a **reading activ
 
 ## Config file structure for reading activities
 
-The structure for a reading activity is identical to that of an exercise. There are 2 big differences: the value of `type` must be set to `content` and keys that are not relevant for exercises can be omitted. The format of the description is also identical.
+The structure for a reading activity is identical to that of an exercise. There are two big differences: the value of `type` must be set to `content` and keys that are not relevant for exercises can be omitted. The format of the description is also identical.
 
 - **`type`**: Must be set to `content` for reading activities
 - **`access`** (`public` or `private`): determines who can use this exercise
@@ -97,7 +97,6 @@ The structure for a reading activity is identical to that of an exercise. There
     "memory_limit": 100000000
   },
   "programming_language": "python",
-  "author": "Firstname Lastname <[email protected]>",
-  "contact": "[email protected]"
+  "contact": "Firstname Lastname <[email protected]>"
 }
 ```

en/references/exercise-description/index.md

@@ -249,13 +249,13 @@ You can easily render code fragments in a monospaced font with syntax highlighti
 When using HTML, wrap your code with `<code>` and `</code>`:
 
 ```html
-In your solution, you can use variable <code>someVariable</code>.
+In your solution, you can use variable <code>some_variable</code>.
 ```
 
-In Markdown, wrap your code with backticks (\`):
+In Markdown, wrap your code with backticks (\`). You can even add the programming language's syntax highlighting with `{:.language-python}` for example.
 
 ```markdown
-In your solution, use can use variable `someVariable`.
+In your solution, use can use variable `some_variable`. Use the abbreviated notation `result += 1`{:.language-python}.
 ```
 
 ### Code blocks
@@ -301,6 +301,14 @@ Using Markdown, Dodona can automatically add syntax highlighting if you provide
     let a = 5;
     let b = 42;
     ```
+Syntax highlighting for the Python doctest format can be obtained this way:
+
+    ```console?lang=python&prompt=>>>
+    >>> echo("Hello world!")
+    "Hello world!"
+    >>> echo(5)
+    5
+    ```
 
 ## Callouts
 

en/references/judges/index.md

@@ -6,7 +6,7 @@ order: 6
 
 # Judges
 
-On this page you can find an overview of all judges that are available on Dodona. A judge is a piece of software that is responsible for testing the solutions of students and writing the results in a format that Dodona understands.
+On [this page](https://dodona.be/en/judges/) you can find an overview of all judges that are available on Dodona. A judge is a piece of software that is responsible for testing the solutions of students and writing the results in a format that Dodona understands.
 
 Most judges only support one programming language, but there are also judges like [TESTed](#TESTed) that support multiple programming languages.
 

en/references/tested/dsl/index.md

@@ -73,7 +73,7 @@ In most cases, it is fine to leave the description empty.
 Each context must have at least one test case.
 Since each context is executed separately, the following two constraints apply:
 
-- Only the first test case may have a "main call", i.e. command line arguments or stdin.
+- Only the first test case may have a "main call", i.e. command line arguments or _stdin_.
 - Only the last test case may have a test for the program's exit code.
 
 Do note that the first and last test case may be the same one:
@@ -84,7 +84,7 @@ if you only have one test case, it may be a main call and have a check for the e
 Test cases are the building blocks of a test suite, and contain some input and the expected outputs (the _tests_).
 Within each context, the following constraints apply to test cases:
 
-- Only the first test case may have a "main call", i.e. command line arguments or stdin.
+- Only the first test case may have a "main call", i.e. command line arguments or _stdin_.
 - Only the last test case may have a test for the program's exit code.
 
 Do note that the first and last test case may be the same one:

en/references/tested/index.md

@@ -75,7 +75,7 @@ We'll explain how to create a simple programming exercise that uses TESTed to pr
 and how to make the exercise available on Dodona.
 The exercise is called "echo" and has the following problem statement:
 
-> Define a function `echo` that outputs its string argument to stdout.
+> Define a function `echo` that outputs its string argument to _stdout_.
 
 Here are some correct submissions for this exercise in a couple of different programming languages:
 
@@ -203,7 +203,7 @@ We'll use the problem statement from above and add an example.
 Create a file `echo/description/description.en.md` with the following content:
 
 ````markdown
-Define a function `echo` that outputs its string argument to stdout.
+Define a function `echo` that outputs its string argument to _stdout_.
 
 ### Example in Python
 
@@ -250,7 +250,7 @@ This test suite specifies that:
 1. All feedback is included in a single tab called _Echo_.
 2. The tab contains feedback on a single test case.
 3. The test case calls the function `echo` with a string argument `"input-1"`.
-4. The expected behavior of the test case is that the text `input-1` is generated on stdout.
+4. The expected behavior of the test case is that the text `input-1` is generated on _stdout_.
 
 
 The file structure now looks like this:

en/references/tested/json/index.md

@@ -135,7 +135,7 @@ A test case is a statement or an expression that will be executed and evaluated.
 Each context has at least one test case.
 The following two constraints apply:
 
-- Only the first test case may have a "main call", i.e. command line arguments or stdin.
+- Only the first test case may have a "main call", i.e. command line arguments or _stdin_.
 - Only the last test case may have a test for the program's exit code.
 
 Do note that the first and last test case may be the same one:
@@ -255,7 +255,7 @@ Here's an overview of all output channels currently supported by TESTed:
 
 ### EmptyChannel
 
-An `EmptyChannel` describes that no output is expected on a specific file descriptor (e.g. stdout or stderr).
+An `EmptyChannel` describes that no output is expected on a specific file descriptor (e.g. _stdout_ or _stderr_).
 Any output generated will be considered as incorrect by TESTed.
 The `EmptyChannel` is represented by a string constant `none`.
 
@@ -273,7 +273,7 @@ For most output types, this is the default value, meaning you don't need to spec
 
 ### IgnoredChannel
 
-An IgnoredChannel object describes that no output is expected on a specific file descriptor (e.g. stdout or stderr).
+An IgnoredChannel object describes that no output is expected on a specific file descriptor (e.g. _stdout_ or _stderr_).
 Any output generated on the file descriptor will be ignored, and is considered correct by TESTed.
 In other words, if you do not want output, you should use [`EmptyChannel`](#emptychannel),
 while if you don't care about the output, you should use `IgnoredChannel`.
@@ -422,8 +422,8 @@ TESTed currently supports the following two oracles:
 
 ### TextOutputChannel
 
-A `TextOutputChannel` object represents text that is expected to be generated on an output channel (e.g. stdout or
-stderr).
+A `TextOutputChannel` object represents text that is expected to be generated on an output channel (e.g. _stdout_ or
+_stderr_).
 
 For example, if the text `"Hello world"` must be written to `stdout`:
 

nl/faq/activities/index.md

@@ -13,3 +13,13 @@ Op de startpagina van Dodona kan je al jouw concepten terugvinden onder _Ongepub
 
 ## Hoe maak ik nieuwe oefeningen aan? <Badge type="tip" text="lesgever" />
 Als lesgever kan je gebruikmaken van de honderden oefeningen die in Dodona aanwezig zijn, maar je kan ook zelf nieuwe oefeningen aanmaken. Je kan hiervoor [dit stappenplan](/nl/guides/exercises/creating-exercises/introduction) volgen.
+
+## Wat is het verschil tussen een cursus en een repository? <Badge type="tip" text="teacher" />
+In Dodona is een "oefeningen _repository_" een verzameling oefeningen en leesactiviteiten die beheerd worden in een gelinkte GitHub repository.
+Deze oefeningen kunnen dan gebruikt worden in meerdere "cursussen".
+
+Een "cursus" in Dodona is opnieuw een verzameling oefeningen en leesactiviteiten gestructureerd in reeksen. Hier kan je bijvoorbeeld oefeningen structureren volgens een gewenst leerpad.
+Cursussen worden volledig beheerd binnen Dodona.
+Een cursus kan oefeningen van verschillende oefeningen repositories bevatten.
+Bij een cursus horen ook de ingeschreven studenten.
+In een cursus kan je deze studenten opvolgen, evaluaties maken, vragen beantwoorden, etc...

nl/faq/annotations/index.md

@@ -59,7 +59,7 @@ Je zal ook een melding zien in de bovenste navigatiebalk van je cursus. Klik op
 
 ![img.png](./course_question_list.png)
 
-Als je alle open vragen over al je cursussen wil zien, kan je naar de pagina `vragen` gaan in de linkse navigatiebalk van Dodona.
+Als je alle open vragen over al je cursussen wil zien, kan je naar de pagina `Vragen` gaan in de linkse navigatiebalk van Dodona.
 
 ![img.png](./questions_index_page.png)
 
@@ -86,11 +86,11 @@ Je kan een algemene opmerking toevoegen door op de knop `Globale opmerking toevo
 ## Hoe kan ik opmerkingen opslaan en hergebruiken? <Badge type="tip" text="lesgever" />
 Studenten maken vaak dezelfde fouten, of hebben gelijkaardige vragen. Om te vermijden dat je dezelfde opmerkingen steeds opnieuw moet schrijven, kan je opmerkingen hergebruiken.
 
-Tijdens het schrijven of bewerken van een opmerking kan je `opmerking opslaan` aanvinken. Dit zal je toelaten om een titel toe te voegen aan de opmerking, wat je zal helpen om de opmerking in de toekomst terug te vinden.
+Tijdens het schrijven of bewerken van een opmerking kan je `Sla opmerking op` aanvinken. Dit zal je toelaten om een titel toe te voegen aan de opmerking, wat je zal helpen om de opmerking in de toekomst terug te vinden.
 
 ![Save comment while writing](./save-comment-edit.png)
 
-Je kan ook een bestaande opmerking opslaan door op `opmerking opslaan` te klikken in het menu van de opmerking.
+Je kan ook een bestaande opmerking opslaan door op `Opmerking opslaan` te klikken in het menu van de opmerking.
 
 ![Save existing comment](save-comment-edit.png)