docs: document challenge types and when they are generated

* doc: Document challenge types and when they are generated

* doc: Fix screenshot paths

* doc: Make summary of challenge type a list

* Add img alt text

* docs: Respond to review comments

docs/courses/README.md

@@ -47,7 +47,7 @@ You'll need to have an idea on basic terminology used in LibreLingo:
 These concepts represent a hierarchical structure to LibreLingo course material: `Courses > Modules > Skills`
 
 - The **target language** is the language the course is meant to teach.
-- The **source langauge** is a language that users of the course are assumed to know.
+- The **source language** is a language that users of the course are assumed to know.
 
 
 <a id="exploring-courses"></a>
@@ -65,7 +65,7 @@ When you enter a course page, for example the [Spanish course](https://libreling
 
 "Skills" are units of course content focused on a particular topic. Each skill is a set of new knowledge, such as new words or phrases.  Skills can focus on vocabulary and follow a theme: the "Animal" skill has words and phrases related to animals, the "Food" skill is all about food. Skills can also focus on teaching grammar.
 
-Inside a skill YAML file there are some keys that you might want to learn of, which is exaplained in detail [here](course.md).
+Inside a skill YAML file there are some keys that you might want to learn of, which is explained in detail [here](skill.md).
 
 <a id="things-new-contributors"></a>
 ### Things you can do as a new contributor

docs/courses/challenge.md

@@ -0,0 +1,97 @@
+# LibreLingo Documentation on Challenge
+
+As they study using LibreLingo, users respond to a series of tasks or questions called **Challenge**s.
+
+Challenges are not configured directly, but [automatically generated from Skill configuration](skill.md#how-skills-are-taught-to-the-user).
+
+---
+
+**Confused?**
+[Ask people](https://github.com/kantord/LibreLingo/discussions) on GitHub Discussions.
+
+---
+
+**Table of Contents:**
+- [Challenge order](#challenge-order)
+- [Cards challenge](#cards-challenge)
+- [Short input challenge](#short-input-challenge)
+- [Options challenge](#options-challenge)
+- [Chips challenge](#chips-challenge)
+- [Listening challenge](#listening-challenge)
+
+## Challenge order
+
+Within a skill, the order of words and phrases is random, but certain challenge types always come before other types. This is denoted by the *Priority* values listed under each challenge type. First priority challenges come before second priority challenges, which come before third priority challenges.
+
+## Cards challenge
+
+![Text asks the user: which of these is "river"?. Below this heading are three cards. Each card contains a Spanish word and corresponding image. In the center the correct choice (río) is selected.](/docs/screenshots/cards-challenge.png)
+
+- *Generated from:* `New words` only
+- *Task:* translation, multiple-choice
+- *Direction:* source -> target only
+- *Properties used:* `Word`, `Translation`, `Images` -- both of the asked word and of two or three other words in the same skill
+- *Mini-dictionary available:* No
+- *Priority*: First
+
+In this challenge type, the user is presented with a word in their source language, and three (four on mobile) cards to choose from. Each card contains a target language word and a matching image, the latter of which functions as a big hint since the user may have never seen this target language word before.
+
+Note that for each card, a random image is selected from the word's `Images` array.
+
+## Short input challenge
+
+![Text asks the user to type the word "river" in Spanish. Below this heading is a text box, and underneath that a set of buttons to insert Spanish-specific characters. At right is an image of a river.](/docs/screenshots/short-input-challenge.png)
+
+- *Generated from:* `New words` only
+- *Task:* translation, free-form
+- *Direction:* source -> target only
+- *Properties used:* `Word`, `Translation`, `Images`
+- *Mini-dictionary available:* Yes
+- *Priority*: Second
+
+In this challenge type, the user is presented with a word in their source language, and a text box in which to input the translation into the target language. There is also a random image from the `Images` array on the right, but since this challenge asks for the target language, the image does not give the user any additional information. If the user does need a hint, the mini-dictionary is available for this challenge.
+
+## Options challenge
+
+![Text asks the user which one of the options is \"Let's go to the beach!\". Below this question are three Spanish sentences with radio buttons to their left.](/docs/screenshots/options-challenge.png)
+
+- *Generated from:* `Phrases` only
+- *Task:* translation, multiple-choice
+- *Direction:* source -> target only
+- *Properties used:* `Phrase`, `Translation` both of the asked phrase and two other phrases in the same skill
+- *Mini-dictionary available:* No
+- *Priority*: First
+
+In this challenge type, the user is presented with a phrase in their source language, and three options from which they must choose the correct translation into the target language. There are no hints available.
+
+## Chips challenge
+
+![Text instructs the user to translate the phrase "Let's go to the beach!". At the bottom of the image, there is a group of draggable Spanish words.](/docs/screenshots/chips-challenge.png)
+
+- *Generated from:* `Phrases` only
+- *Task:* translation, set of words provided
+- *Direction:* Both directions: source -> target, target -> source
+- *Properties used:*
+  - If source -> target: `Phrase`, `Translation`, `Alternative translations`; `Translation` and `Alternative translations` of other phrases anywhere in the course
+  - If target -> source: `Translation`, `Phrase`, `Alternative versions`; `Phrase` and `Alternative versions` of other phrases anywhere in the course
+- *Mini-dictionary available:* Yes
+- *Priority*: Third
+
+In this challenge type, the user is presented with a phrase in one language and a set of words in the other language. This set will always include all words of the `Translation` field. The user's task is to use this words as "building blocks" to create *any* acceptable translation for the phrase they've been presented with.
+
+The mini-dictionary is available to give hints about individual words but there are no hints about grammar or sentence structure.
+
+The chips will never include exact duplicates of each other.
+
+## Listening challenge
+
+![Text instructs the user: "Type what you hear". Below this heading is a text box, and underneath that a set of buttons to insert Spanish-specific characters.](/docs/screenshots/listening-challenge.png)
+
+- *Generated from:* `New words` and `Phrases`
+- *Task:* transcription
+- *Direction:* N/A, target language only
+- *Properties used:* `Word` or `Phrase`
+- *Mini-dictionary available:* No
+- *Priority*: Second
+
+In this challenge type, the user is played audio of a word or phrase in the target language, and is presented with a text box to transcribe the audio (still in the target language). The user can re-listen to the audio, if necessary.

docs/courses/skill.md

@@ -1,10 +1,10 @@
 # LibreLingo Documentation on Skill
 
-A **Skill** resides below a Module within the course structure. It's the lowest element in the course hierarchy. It contains data regarding what questions LibreLingo will ask the users.
+A **Skill** resides below a Module within the course structure. It's the lowest element in the course hierarchy. It contains a set of words and phrases to be taught to the user.
 
 A skill is usually centered around a specific theme. This could be introducing a new grammar concept or just vocabulary to talk about a certain topic.
 
-To get a better understanding, you can read the [course basics](README.md#basics).
+The words and phrases that make up a skill are taught to the user using [automatically generated questions and tasks](#how-skills-are-taught-to-the-user).
 
 ---
 
@@ -17,6 +17,7 @@ To get a better understanding, you can read the [course basics](README.md#basics
 - [Tree structure](#tree-structure)
 - [`(skill_name).yaml`](#yaml)
 - [Data breakdown](#data-breakdown)
+- [How skills are taught to the user](#how-skills-are-taught-to-the-user)
 - [Creating new skills](#creating-new)
 - [Examples of editing a skill](#example-edit)
 - [Tips for creating good skills](#tips)
@@ -108,17 +109,18 @@ Mini-dictionary:
 - `Skill > Id`: The ID of the course. **NOTE:** This should be unchanged if you're translating or editing existing course. Only if you're creating a new course, this should have a unique [UUID v4](https://www.uuidgenerator.net/version4) string. Details for which you can find [here](creating-courses.md).
 - `Skill > Thumbnails`: A list of filenames of the thumbnails to be used on the course page to give an idea of the skill. A list of available files can be found on [`apps/web/static/images/`](https://github.com/kantord/LibreLingo/tree/main/apps/web/static/images). The names should be used without extension and without `_tiny` or `_tinier` parts. e.g. `banana2_tinier.jpg` should be written as `banana2`.
 
-**`New words`** has a list of new words that the lesson asks about.
-- `Word`: The word in destination language.
+**`New words`** has a list of new words that the lesson teaches.
+- `Word`: The word in the target language, i.e. the language the user is learning.
 - `Synonyms`: A list of synonyms of the above word. (optional)
-- `Translation`: Translation of the word in target audience's language.
-- `Also accepted`: A list of synonyms of the `Translation` word above. (optional)
+- `Translation`: Translation of the word in the source language, i.e. the language the user already knows.
+- `Also accepted`: A list of alternative translations to the source language, which will *not* be taught, but will be accepted as correct translations of the `Word` field if supplied by the user. Currently has no effect, but may be used by future challenge types. (optional)
 - `Images`: A list of images for the word that is defined under `Word` or `Translation` above. The image names has to be without extension and without `_tiny` or `_tinier` part.
 
-**`Phrases`** has a list of sentences or phrases that the lession asks about.
-- `Phrase`: The phrase in destination language. e.g. In this case, it's written in Spanish.
-- `Alternative versions`: An alternative version of the above phrase. (optional)
-- `Translation`: Translation of the phrase in target audience's language. e.g. In this case, it's written in English.
+**`Phrases`** has a list of sentences or phrases that the lesson teaches.
+- `Phrase`: The phrase in the target language.
+- `Alternative versions`: A list of alternative versions of the phrase in the target language. These will *not* be taught, but will be accepted as correct translations of the `Translation` field if supplied by the user. (optional)
+- `Translation`: Translation of the phrase to the source language.
+- `Alternative translations`: A list of alternative translations to the source language, which will *not* be taught, but will be accepted as correct translations of the `Phrase` field if supplied by the user. (optional)
 
 **`Mini-dictionary`** has a list of terms and meanings the user can view as a sort of "hint" if they are stuck. Entries are accessed by mousing over terms in an exercise, which brings up a tooltip with the corresponding term(s) in the other language. An entry is required for every term used in a skill.
 
@@ -131,6 +133,20 @@ Note that all `New words` are automatically added to the `Mini-dictionary`, in b
 - `<destination language>`: A list of terms in destination language as key and meaning in target audience's language.
 - `<target audience's language>`: A list of terms in target audience's language as key and meaning in destination language.
 
+## How skills are taught to the user
+
+As the course author, you have to specify the words and phrases you want to teach. LibreLingo will know how to present skills as a series of individual questions and tasks -- LibreLingo calls these "challenges." It is useful to understand what challenges will be generated.
+
+For each vocabulary word (that is, each `New words` entry) in a skill, LibreLingo generates:
+- A [cards challenge](challenge.md#cards-challenge) -- multiple-choice translation from source language to target language, with a visual clue
+- A [short input challenge](challenge.md#short-input-challenge) -- free-form translation from source language to target language
+- A [listening challenge](challenge.md#listening-challenge) -- transcription from target language audio to target language text
+
+For each phrase in a skill, LibreLingo generates:
+- An [options challenge](challenge.md#options-challenge) -- multiple-choice translation from target language to source language
+- Two [chips challenges](challenge.md#chips-challenge) -- translation using provided words, one in each translation direction, unless the phrase is one word
+- A [listening challenge](challenge.md#listening-challenge) -- transcription from target language audio to target language text
+
 <a id="creating-new"></a>
 ## Creating new skills
 
@@ -222,4 +238,3 @@ courses/spanish-from-english/basics/skills
 
 You can use this Markdown file to create a short article about the skill the user is about to learn or practice.
 This can be useful to explain grammatical concepts, gotchas and learning tips about the specific skill.
-