From 3aeb0336c989186cf0db169c5cb88e6e9ee483dd Mon Sep 17 00:00:00 2001 From: Martin Polanka Date: Wed, 11 Jan 2017 23:23:46 +0100 Subject: [PATCH] WIP: restruct user doc --- Rewritten-docs.md | 124 ++++++++++++++++++++++++++++++---------------- 1 file changed, 82 insertions(+), 42 deletions(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index 7277ece..95e0aa5 100644 --- a/Rewritten-docs.md +++ b/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