WIP: restruct user doc

Rewritten-docs.md

@@ -2049,28 +2049,23 @@ Loading results means fetching archive from fileserver, parsing the main YAML
 file generated by worker and saving data to the database. Also, points are
 assigned by score calculator.
 
-User documentation
-==================
 
-Web Application
----------------
+# User documentation
 
 @todo: Describe different scenarios of the usage of the Web App
 
-### Terminology
+@todo: Describe the requirements of running the web application (modern web browser, enabled CSS, JavaScript, Cookies & Local storage)
+
+## Terminology
 
 @todo: Describe the terminology: Instance, User, Group, Student,
 Supervisor, Admin
 
-### Web application requirements
-
-@todo: Describe the requirements of running the web application (modern
-web browser, enabled CSS, JavaScript, Cookies & Local storage)
+## General basics
 
+@todo: actions which are available for all users
 
-### Scenario \#1: Becoming a user of ReCodEx
-
-#### How to create a user account?
+### How to create a user account?
 
 You can create an account if you click on the “*Create account*” menu
 item in the left sidebar. You can choose between two types of
@@ -2091,7 +2086,7 @@ When crating your account both ways, you must select an instance your
 account will belong to by default. The instance you will select will be
 most likely your university or other organization you are a member of.
 
-#### How to get into ReCodEx?
+### How to get into ReCodEx?
 
 To log in, go to the homepage of ReCodEx and in the left sidebar choose
 the menu item “*Sign in*”. Then you must enter your credentials into one
@@ -2102,7 +2097,7 @@ Authentication Service (CAS), you should put your student’s number and
 your CAS password into the second form called “Sign into ReCodEx using
 CAS UK”.
 
-#### How do I sign out of ReCodEx?
+### How do I sign out of ReCodEx?
 
 If you don’t use ReCodEx for a whole day, you will be logged out
 automatically. However, we recommend you sign out of the application
@@ -2113,7 +2108,7 @@ have to expand the sidebar with a button next to the “*ReCodEx*” title
 
 @todo: Simon's image
 
-#### What to do when you cannot remember your password?
+### What to do when you cannot remember your password?
 
 If you can’t remember your password and you don’t use CAS UK
 authentication, then you can reset your password. You will find a link
@@ -2132,7 +2127,7 @@ If you sign in through CAS UK, then please follow the instructions
 provided by the administrators of the service described on their
 website.
 
-#### How to configure your account?
+### How to configure your account?
 
 There are several options you have to edit your user account.
 
@@ -2145,87 +2140,78 @@ You can access the settings page through the “*Settings*” button right
 under your name in the left sidebar.
 
 
-### Scenario \#2: User is a student
+## Student
 
 @todo: describe what it means to be a “student” and what are the
 student’s rights
 
-#### How to join a group for my class?
+### How to join a group for my class?
 
 @todo: How to join a specific group
 
-#### Which assignments do I have to solve? 
+### Which assignments do I have to solve? 
 
 @todo: Where the student can find the list of the assignment he is
 expected to solve, what is the first and second deadline.
 
-#### Where can I see details of my classes’ group?
+### Where can I see details of my classes’ group?
 
 @todo: Where can the user see groups description and details, what
 information is available.
 
-#### How to submit a solution of an assignment?
+### How to submit a solution of an assignment?
 
 @todo: How does a student submit his solution through the web app
 
-#### Where are the results of my solutions?
+### Where are the results of my solutions?
 
 @todo: When the results are ready and what the results mean and what to
 do about them, when the user is convinced, that his solution is correct
 although the results say different
 
-#### How can I discuss my solution with my teacher/group’s supervisor directly through the web application?
+### How can I discuss my solution with my teacher/group’s supervisor directly through the web application?
 
 @todo: Describe the comments thread behavior (public/private comments),
 who else can see the comments, how notifications work (*not implemented
 yet*!).
 
 
-### Scenario \#3: User is supervisor of a group
+## Group supervisor
 
 @todo: describe what it means to be a “supervisor” of a group and what
 are the supervisors rights
 
-#### How do I become a supervisor of a group?
+### How do I become a supervisor of a group?
 
 @todo: How does a user become a supervisor of a group?
 
-#### How to add or remove a student to my group?
+### How to add or remove a student to my group?
 
 @todo: How to add a specific student to a given group
 
-#### How do I add another supervisor to my group?
-
-@todo: who can add another supervisor, what would be the rights of the
-second supervisor
-
-#### How do I create a subgroup of my group?
-
-@todo: What it means to create a subgroup and how to do it.
-
-#### How do I assign an exercise to my students?
+### How do I assign an exercise to my students?
 
 @todo: Describe how to access the database of the exercises and what are
 the possibilities of assignment setup – availability, deadlines, points,
 score configuration, limits
 
-#### How do I configure the limits of an assignment and how to choose appropriate limits?
+### How do I configure the limits of an assignment and how to choose appropriate limits?
 
 @todo: Describe the form and explain the concept of reference solutions.
 How to evaluate the reference solutions for the exercise right now (to
 get the up-to-date information).
 
-#### How can I assign some exercises only to some students of the group?
+### How can I assign some exercises only to some students of the group?
 
 @todo: Describe how to achieve this using subgroups
 
-#### How can I see my students’ solutions?
+### How can I see my students’ solutions?
 
 @todo Describe where all the students’ solutions for a given assignment
 can be found, where to look for all solutions of a given student, how to
 see results of a specific student’s solution’s evaluation result.
 
-#### Can I assign points to my students’ solutions manually instead of depending on automatic scoring?
+### Can I assign points to my students’ solutions manually instead of depending on automatic scoring?
 
 @todo If and how to change the score of a solution – assignment
 settings, setting points, bonus points, accepting a solution (*not
@@ -2233,13 +2219,67 @@ implemented yet!*). Describe how the student and supervisor will still
 be able to see the percentage received from the automatic scoring, but
 the awarded points will be overridden.
 
-#### How can I discuss student’s solution with him/her directly through the web application?
+### How can I discuss student’s solution with him/her directly through the web application?
 
 @todo: Describe the comments thread behavior (public/private comments),
 who else can see the comments -- same as from the student perspective
 
 
-### Writing job configuration
+## Group administrator
+
+@todo: who is this?
+
+### How do I add another supervisor to my group?
+
+@todo: who can add another supervisor, what would be the rights of the
+second supervisor
+
+### How do I create a subgroup of my group?
+
+@todo: What it means to create a subgroup and how to do it.
+
+
+## Superadministrator
+
+Superadmin is user with the most priviledges and as such superadmin should be
+quite unique role. Ideally there should be only one of this kind, used with
+special caution and adequate security. With this stated it is obvious that
+superadmin can perform any action the API is capable of.
+
+### Users management
+
+There are only few roles to which users can belong in ReCodEx. Basically there
+are only three: _student_, _supervisor_, and _superadmin_. Base role is student
+which is assigned to every registered user. Roles are stored in database
+alongside other information about user. One user always has only one role at the
+time. At first startup of ReCodEx administrator should create his account and
+then change role in database by hand. After that manual intervention into
+database should never be needed.
+
+There is a little catch in groups and instances management. Groups can have
+admins and supervisors. This setting is valid only per one particular group and
+has to be separated from basic role system. This implies that supervisor in one
+group can be student in another and simultaneously have global supervisor role.
+Changing role from student to supervisor and back is done automatically by
+application and should not be managed by hand in database! Previously stated
+information can be applied to instances as well, but instances can only have
+admins.
+
+Roles description:
+
+- Student -- Default role which is used for newly created accounts. Student can
+  join or leave public groups and submit solutions of assigned exercises.
+- Supervisor -- Inherits all permissions from student role. Can manage groups to
+  which he/she belongs to. Supervisor can also view and change groups details,
+  manage assigned exercises, view students in group and their solutions for
+  assigned exercises. On top of that supervisor can create/delete groups too,
+  but only as subgroup of groups he/she belongs to.
+- Superadmin -- Inherits all permissions from supervisor role. Most powerful
+  user in ReCodEx who should be able to do everything which is provided by
+  application.
+
+
+## Writing job configuration
 
 To run and evaluate an exercise the backend needs to know the steps how to do
 that. This is different for each environment (operation system, programming