MDL-12312 Reviewed and slightly improved Petr's great help file

diff --git a/lang/en_utf8/help/grade/aggregation.html b/lang/en_utf8/help/grade/aggregation.html
index c4f9a4db9983ffbefc4534bc56c63ab324c81af2..6bdb0de7dbedad98b7a290444031647475db091e 100644 (file)
--- a/lang/en_utf8/help/grade/aggregation.html
+++ b/lang/en_utf8/help/grade/aggregation.html
@@ -2,7 +2,7 @@
 <p>This menu lets you choose the aggregation strategy that will be used to calculate
 each participant's overall grade for this category. The different options are explained below.</p>
 
-<p>The grades are first converted to percentage values (interval from 0 to 1), then aggregated using one of
+<p>The grades are first converted to percentage values (interval from 0 to 1, this is called normalisation), then aggregated using one of
 the function bellow and finally converted to requested range of associated category item (<em>Minimum grade</em> and <em>Maximum grade</em>).</p>
 
 <p><strong>Important</strong>: An empty grade is simply a missing gradebook entry, and could
@@ -10,69 +10,58 @@ mean different things. For example, it could be a participant who hasn't yet sub
 an assignment submission not yet graded by the teacher, or a grade that has been manually deleted by
 the gradebook administrator. Caution in interpreting these "empty grades" is thus advised.</p>
 
-<table class="generaltable boxaligncenter" cellpadding="4" cellspacing="1" summary="Aggregation strategies for grading categories">
-    <tr>
-        <th class="header">Strategy</th><th class="header">Description</th><th class="header">Example (A1..A3 assignment grades)</th>
-    </tr>
-    <tr>
-        <td class="cell">Mean of grades</td>
-        <td class="cell">All grades summed and divided by the total number of grades.</td>
-        <td class="cell">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
-                         <code>(0.7 + 0.25 + 1.0)/3 = 0.65 --> 65/100</code></td>
-    </tr>
-    <tr>
-        <td class="cell">Weighted mean</td>
-        <td class="cell">Each grade item can be given a weight, which is then used in the arithmetic mean aggregation to influence
-                         the importance of each item in the overall mean.</td>
-        <td class="cell">A1 70/100 weight 10, A2 20/80 weight 5, A3
-                         10/10 weight 3, category max 100:<br /><code>(0.7*10 + 0.25*5 + 1.0*3)/18 = 0.625 --> 62.5/100</code></td>
-    </tr>
-    <tr>
-        <td class="cell">Simple weighted mean</td>
-        <td class="cell">The difference from <em>Weighted mean</em> is that weight is calculated as <em>Maximum grade</em> - <em>Minimum grade</em>
-                         for each item. 100 point assignment has weight 100, 10 point assignment has weight 10.</td>
-        <td class="cell">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
-                         <code>(0.7*100 + 0.25*80 + 1.0*10)/190 = 0.526 --> 52.6/100</code></td>
-    </tr>
-    <tr>
-        <td class="cell">Mean of grades (with extra credits)</td>
-        <td class="cell">Arithmetic mean with a twist. An old, now unsupported aggregation strategy provided here only
-                         for backward compatibility with old activities.</td>
-        <td class="cell">&nbsp;</td>
-    </tr>
-    <tr>
-        <td class="cell">Median of grades</td>
-        <td class="cell">The median is calculated by counting all the grades and selecting the grade that falls in the middle of that count
+<dl id="grade-aggregation-help">
+    <dt>Mean of grades</dt>        
+    <dd>The sum of all grades divided by the total number of grades.</dd>
+    <dd class="example">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
+                     <code>(0.7 + 0.25 + 1.0)/3 = 0.65 --> 65/100</code></dd>
+                     
+    <dt>Weighted mean</dt>
+        <dd>Each grade item can be given a weight, which is then used in the arithmetic mean aggregation to influence
+                         the importance of each item in the overall mean.</dd>
+        <dd class="example">A1 70/100 weight 10, A2 20/80 weight 5, A3
+                         10/10 weight 3, category max 100:<br /><code>(0.7*10 + 0.25*5 + 1.0*3)/18 = 0.625 --> 62.5/100</code></dd>
+    
+    <dt>Simple weighted mean</dt>
+        <dd>The difference from <em>Weighted mean</em> is that weight is calculated as <em>Maximum grade</em> - <em>Minimum grade</em>
+                         for each item. 100 point assignment has weight 100, 10 point assignment has weight 10.</dd>
+        <dd class="example">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
+                         <code>(0.7*100 + 0.25*80 + 1.0*10)/190 = 0.526 --> 52.6/100</code></dd>
+    
+    <dt>Mean of grades (with extra credits)</dt>
+        <dd>Arithmetic mean with a twist. An old, now unsupported aggregation sdtategy provided here only
+                         for backward compatibility with old activities.</dd>
+    
+    <dt>Median of grades</dt>
+        <dd>The median is calculated by sorting all the grades and selecting the grade that falls in the middle of that 
                          (or the mean between the two middle grades if there is an even number of grades). The advantage over the mean is
-                         that it is not affected by outliers (grades which are uncommonly far from the mean).</td>
-        <td class="cell">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
-                         <code>0.7 + 0.25 + 1.0 --> 0.25 --> 25/100</code></td>
-    </tr>
-    <tr>
-        <td class="cell">Smallest grade</td>
-        <td class="cell">The result is the relatively smallest grade. It is usually used in combination with <em>Aggregate only non-empty grades</em>.</td>
-        <td class="cell">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
-                         <code>min(0.7 + 0.25 + 1.0) = 0.25 --> 25/100</code></td>
-    </tr>
-    <tr>
-        <td class="cell">Highest grade</td>
-        <td class="cell">The result is the relatively highest grade.</td>
-        <td class="cell">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
-                         <code>max(0.7 + 0.25 + 1.0) = 1.0 --> 100/100</code></td>
-    </tr>
-    <tr>
-        <td class="cell">Mode of grades</td>
-        <td class="cell">The mode is the grade that occurs the most frequently. It is more often used for non-numerical grades.
-                         The advantage over the mean is that it is not affected by outliers (grades which are uncommonly far from the mean).</td>
-        <td class="cell">&nbsp;</td>
-    </tr>
-    <tr>
-        <td class="cell">Sum of grades</td>
-        <td class="cell">The sum of all grade values. Scale grades are ignored. This is the only type that does not convert the
-                         grades to percentages internally. The <em>Maximum grade</em> of associated category item is calculated
-                         automatically as a sum of maximums from all aggregated items.</td>
-        <td class="cell">A1 70/100, A2 20/80, A3 10/10:<br />
-                         <code>70 + 20 + 10 = 100/190</code></td>
-    </tr>
-
-</table>
+                         that it is not affected by outliers (grades which are uncommonly far from the mean).</dd>
+        <dd class="example">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
+                         <code>0.7 + 0.25 + 1.0 --> 0.25 --> 25/100</code></dd>
+    
+    <dt>Smallest grade</dt>
+        <dd>The result is the smallest grade after normalisation. It is usually used in combination with <em>Aggregate only non-empty grades</em>.</dd>
+        <dd class="example">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
+                         <code>min(0.7 + 0.25 + 1.0) = 0.25 --> 25/100</code></dd>
+                         
+    <dt>Highest grade</dt>
+        <dd>The result is the highest grade after normalisation.</dd>
+        <dd class="example">A1 70/100, A2 20/80, A3 10/10, category max 100:<br />
+                         <code>max(0.7 + 0.25 + 1.0) = 1.0 --> 100/100</code></dd>
+    
+    <dt>Mode of grades</dt>
+        <dd>The mode is the grade that occurs the most frequently. It is more often used for non-numerical grades.
+                         The advantage over the mean is that it is not affected by outliers (grades which are uncommonly far from the mean). 
+                         However it loses its meaning once there is more than one most frequently occuring grade (only one is kept), or when all
+                         the grades are different from each other.</dd>
+        <dd class="example">A1 70/100, A2 35/50, A3 20/80, A4 10/10, A5 7/10 category max 100:<br />
+                         <code>mode(0.7; 0.7; 0.25; 1.0; 0.7) = 0.7 --> 70/100</code></dd>
+    
+    <dt>Sum of grades</dt>
+        <dd>The sum of all grade values. Scale grades are ignored. This is the only type that does not convert the
+                         grades to percentages internally (normalisation). The <em>Maximum grade</em> of associated category item is calculated
+                         automatically as a sum of maximums from all aggregated items.</dd>
+        <dd class="example">A1 70/100, A2 20/80, A3 10/10:<br />
+                         <code>70 + 20 + 10 = 100/190</code></dd>
+    </dt>
+</dl>   
\ No newline at end of file