diff --git a/docs/courses/README.md b/docs/courses/README.md index fea085765720..0d834d0c49e2 100644 --- a/docs/courses/README.md +++ b/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. @@ -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). ### Things you can do as a new contributor diff --git a/docs/courses/challenge.md b/docs/courses/challenge.md new file mode 100644 index 000000000000..f1ce472f29f1 --- /dev/null +++ b/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. diff --git a/docs/courses/skill.md b/docs/courses/skill.md index 7c7bc883aef8..83c1bffb4c9b 100644 --- a/docs/courses/skill.md +++ b/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 - ``: A list of terms in destination language as key and meaning in 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 + ## 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. - diff --git a/docs/screenshots/cards-challenge.png b/docs/screenshots/cards-challenge.png new file mode 100644 index 000000000000..1a685c40a75c Binary files /dev/null and b/docs/screenshots/cards-challenge.png differ diff --git a/docs/screenshots/chips-challenge.png b/docs/screenshots/chips-challenge.png new file mode 100644 index 000000000000..dd9672eec65d Binary files /dev/null and b/docs/screenshots/chips-challenge.png differ diff --git a/docs/screenshots/listening-challenge.png b/docs/screenshots/listening-challenge.png new file mode 100644 index 000000000000..bdceaacc2ac8 Binary files /dev/null and b/docs/screenshots/listening-challenge.png differ diff --git a/docs/screenshots/options-challenge.png b/docs/screenshots/options-challenge.png new file mode 100644 index 000000000000..3696859ebfc4 Binary files /dev/null and b/docs/screenshots/options-challenge.png differ diff --git a/docs/screenshots/short-input-challenge.png b/docs/screenshots/short-input-challenge.png new file mode 100644 index 000000000000..1ddc0d075832 Binary files /dev/null and b/docs/screenshots/short-input-challenge.png differ