Merge branch 'master' of https://github.com/ReCodEx/wiki.wiki

Rewritten-docs.md

@@ -1637,7 +1637,7 @@ we will re-evaluate this decision.
 
 #### Communication with the backend
 
-##### Backend failiure reporting
+##### Backend failure reporting
 
 The backend is a separate component which does not communicate with the
 administrators directly. When it encounters an error it stores it in a log file.
@@ -1777,6 +1777,7 @@ Described roles are:
 - Student
 - Group supervisor
 - Group administrator
+- Instance administrator
 - Superadministrator
 
 ## Terminology
@@ -1804,6 +1805,10 @@ They can be shared by the teachers using an exercise database in ReCodEx.
 
 **Assignment** -- An exercise assigned to a group, possibly with modifications.
 
+**Runtime environment** -- @todo
+
+**Hardware group** -- @todo
+
 ## General basics
 
 Description of general basics which are the same for all users of ReCodEx web
@@ -2040,11 +2045,80 @@ to your group.
 
 ### Assigning exercises
 
-@todo: Describe how to access the database of the exercises and what are
+Before assigning exercise you obviously have to know what exercises are
-the possibilities of assignment setup – availability, deadlines, points,
+available. List of all exercises in system can be found under "Exercises" link
-score configuration, limits
+in sidebar. This page contains table with exercises names, difficulties and
-
+names of the authors of exercises. Further information about exercise is
-@todo: How can I assign some exercises only to some students of the group? Describe how to achieve this using subgroups
+available by clicking on its name.
+
+On the exercise details page can be found numerous information about it. There
+is box with all possible localized descriptions and also box with some
+additional information. Like when was exercise created by whom, what is
+difficulty of it, what version is it. There is also description for supervisors
+by exercise author under "Exercise overview" option, where some important
+information can be found. And most notably there is information in what
+programming languages can be exercises solved, this is available under
+"Supported runtime environments" row.
+
+If you decide that exercise is suitable for some of your groups, please note
+"Groups" box at the bottom of the page. There is list of all groups you
+supervise with quick "Assign" button which will assign exercise to some
+particular group.
+
+After clicking on "Assign" button you should be redirected to assignment
+editation page. In there you can find two forms, one for editation of assignment
+meta information and the second one for setting exercise time and memory limits.
+
+In meta information form you can fill these options:
+
+- name of the assignment which will be visible in group
+- visibility, if assignment is under construction then you can mark it as not
+  visible and students will not see it
+- subform for localized descriptions (new localization can be added by clicking
+  on "Add language variant" button, current one deleted with "Remove this
+  language" button)
+    - language of description from dropdown field (english, czech, german)
+    - description in selected language
+- score configuration which will be used on students solution evaluation,
+  description of score configuration can be found further in "Writing score
+  configuration" chapter
+- first submission deadline
+- maximum gainable points before first deadline
+- second submission deadline, after that students still can submit exercises but
+  no points for them
+- maximum gainable points after first deadline and before second deadline
+- submission count limit for students' solutions, after this amount students
+  cannot submit any other solutions
+- visibility of memory and time ratios, if true then students can see for each
+  test percentage of used memory and time
+- minimum percentage of points which submission have to gain otherwise it will
+  gain no points
+- assignment is bonus one and points from it are not included in students
+  overall score
+
+Form has to be submitted with "Edit settings" button otherwise changes will not
+be saved.
+
+The same editation page serves also for the purpose of assignment editation, not
+only creation. That is why on the bottom of the page "Delete the assignment" box
+can be found. Clearly the button "Delete" in there can be used to unassign
+exercise from group.
+
+The last unexplored area is time and memory limits form. The whole form is
+situated in box with tabs which are leading to particular runtime environments.
+If you wish to not use one of these, locate "Remove" button at the bottom of the
+box tab which will delete this environment from assignment. Please note that
+this action is irreversible.
+
+In general one tab in environments box contains some basic information about
+runtime environment and another nested tabbed box. In there you can find all
+hardware groups which are available for exercise and you can set here particular
+limits for all test cases. Time and memory limits can be set to all test cases,
+time limits have to be filled in seconds (float), memory limits are in bytes
+(int). If you are interested in some reference values to particular test case
+then you can take a peek on collapsable "Reference solutions' evaluations" item.
+If you are satisfied with changes you made to limits save form with "Change
+limits" button right under environments box.
 
 ### Students' solutions management
 
@@ -2113,6 +2187,13 @@ clicking on it some particular supervisor should not be supervisor of the group
 anymore.
 
 
+## Instance administrator
+
+@todo: who is this?
+
+@todo: creating groups right in the instance
+
+
 ## Superadministrator
 
 Superadmin is user with the most priviledges and as such superadmin should be
@@ -2153,6 +2234,38 @@ Roles description:
   application.
 
 
+## Writing score configuration
+
+@todo: introduction to scoring, mention that there can be more implementation but for now only simple is available
+
+### Simple score calculation
+
+First implemented calculator is simple score calculator with test weights. This
+calculator just looks at the score of each test and put them together according
+to the test weights specified in assignment configuration. Resulting score is
+calculated as a sum of products of score and weight of each test divided by the
+sum of all weights. The algorithm in Python would look something like this:
+
+```
+sum = 0
+weightSum = 0
+for t in tests:
+  sum += t.score * t.weight
+  weightSum += t.weight
+score = sum / weightSum
+```
+
+Sample score config in YAML format:
+
+```{.yml}
+testWeights:
+  a: 300   # test with id 'a' has a weight of 300
+  b: 200
+  c: 100
+  d: 100
+```
+
+
 ## Writing job configuration
 
 To run and evaluate an exercise the backend needs to know the steps how to do