Changes between Version 11 and Version 12 of BoltIntro

Timestamp:

Oct 3, 2007, 1:53:33 PM (18 years ago)

Author:

davea

Comment:

--

BoltIntro

@@ -29 +29 @@
  * Each student's progress is recorded in a database, and when they return to the course later they resume at that point.
  * Bolt maintain an estimate of each student's mastery of the course material.
-
+ 
 In addition, Bolt lets you create better courses; specifically, you can
  * find out exactly how effective each lesson is;
@@ -47 +47 @@
 == Creating exercises ==
 
+An exercise is a PHP script.
+Here's an example containing a multiple-choice question
+(the '2' indicates that the correct answer is the last one):
 {{{
 <?php
@@ -61 +64 @@
 ?>
 }}}
-
+Here's an example that shows an image;
+a correct answer is a click in the indicated subrectangle.
 {{{
 <?php
@@ -73 +77 @@
 }}}
 
+Bolt supplies functions for other types of questions,
+such as inclusive multiple-choice and fill-in-the-blank.
+An exercise can include multiple questions.
+
+At the implementation level, an exercise has three functions:
+
+ * When invoked with $mode_show set, it shows the exercise.
+ * When invoked with $mode_score set, it computes a score based on the responses stored in $_GET, and assigns the score to $score.  Its text output, if any, is ignored.
+ * When invoked with $mode_answer, it shows and "answer sheet" based on the responses stored in $_GET.  If the response is correct and no answer sheet is to be shown, it sets $no_answer_sheet.
+
+Bolt's exercise primitives perform all these functions for you;
+however, you're free to implement your own exercises.
+
 == Course documents ==
 
-The structure of a Bolt course is defined by a [RFC:4627 JSON] document:
+The structure of a Bolt course is defined by a [RFC:4627 JSON] document.
+Here's an example of a course with two lessons followed by an exercise:
 {{{
 {
    "name": "Identifying Sierra Conifers",
    "description: "Learn to identify the major conifers of California's Sierra Nevada",
-   "content": [
+   "items": [
       {
           "type": "lesson",
@@ -99 +117 @@
 }}}
 
+Course items can be grouped into '''sets'''; for example:
+
+{{{
+{
+   "type": "set",
+   "show_n": 1,
+   "order": "random",
+   "items": {
+      {
+      ...
+      }
+   }
+}
+}}}
+
+The attributes of a set include:
+
+ * show_n: the number of items in the set to show
+ * order: whether to show the items sequentially or randomly
+
+Items (lessons, exercises, and sets) can include '''properties''', e.g.:
+
+{{{
+{
+   "type": "lesson",
+   "name": "The Linnaean hierarchy",
+   "file": "linnaean.html"
+   "properties": {
+      "verbal_level": 12,
+      "detail_level": 0.8
+   }
+},
+}}}
+
+When Bolt has a choice of items (e.g. when it encounters a set from which a
+single item is to be shown) it calls, for each item, a course-supplied
+'''matchmaking function''', passing to it the student object
+(which includes demographics such as age)
+and the item's properties (represented as a PHP object).
+The matchmaking function returns a number representing the estimated
+effectiveness of that item for that student,
+and Bolt chooses the item with the highest value.
+
 == Policies ==