diff --git a/Rewritten-docs.md b/Rewritten-docs.md index d80945f..040bbf5 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1587,7 +1587,7 @@ checking. Previous chapters implies, that each user has to have a role, which corresponds to his/her privileges. Our research showed, that three roles are sufficient -- student, supervisor and administrator. The user role has to be checked with every request. The good points is, that roles nicely match with -granuality of API endpoints, so the permission checking can be done at the +granularity of API endpoints, so the permission checking can be done at the beginning of each request. That is implemented using PHP annotations, which allows to specify allowed user roles for each request with very little of code, but all the business logic is the same, together in one place. @@ -1629,7 +1629,7 @@ jobs which failed on a worker hardware issue. These jobs are typically submitted by different user than the author (an administrator for example), so the original authors should be notified. In this case it is more reasonable to load the results immediately and optionally send them a notification via an email. -This is exactely what we do. +This is exactly what we do. It seems with the benefit of hindsight that immediate loading of all jobs could simplify the code and it has no major drawbacks. In the next version of ReCodEx @@ -1678,7 +1678,7 @@ etc. The easiest solution is to manage this information by hand, every instance of the API server has to have an administrator which would have to fill them. This of course includes only the currently available workers and runtime environments which does not change very often. The real-time statistics of the -backend cannot be made accesible this way in a reasonable way. +backend cannot be made accessible this way in a reasonable way. A better solution is to update this information automatically. This can be done in two ways: @@ -1708,7 +1708,7 @@ One of the downsides is the large number of different web browsers (including the older versions of a specific browser) and their different interpretation of the code (HTML, CSS, JS). Some features of the latest specifications of HTML5 are implemented in some browsers which are used by a subset of the Internet -users. This has to be taken into account when choosing apropriate tools +users. This has to be taken into account when choosing appropriate tools for implementation of a website. There are two basic ways how to create a website these days: @@ -1734,7 +1734,7 @@ There are two basic ways how to create a website these days: based on the data received from the API server. The script file is usually quite large but it can be cached and does not have to be downloaded from the server again (until the cached file expires). Only the data from the API - server needs to be transfered over the Internet and thus reduce the volume of + server needs to be transferred over the Internet and thus reduce the volume of payload on each request which leads to a much more responsive user experience, especially on slower networks. Since the client-side code has full control over the UI and a more sophisticated user interactions with the UI can be @@ -1914,9 +1914,9 @@ instance have own group hierarchy, so you can choose only those from your instance. That is why list of groups is available from instance link located in sidebar. This link brings you to instance detail page. -In there you can see a description of the intance and most importantly in +In there you can see a description of the instance and most importantly in "Groups hierarchy" box there is a hierarchical list of all public groups in the -instance. Please note that groups with plus sign are collapsable and can be +instance. Please note that groups with plus sign are collapsible and can be further extended. If you successfully located group you would like to join, continue by clicking on "See group's page" link following with "Join group" link. @@ -1928,9 +1928,9 @@ link. On the group detail page there are multiple interesting things for you. First one is brief overview with information describing the group, there is list with supervisors and also hierarchy of subgroups. Most importantly there is -"Student's dasboard" section. This section contains list of assignments and list -of fellow students. If supervisors of groups allowed students to see each others -statistics there will also be points which particular students gained. +"Student's dashboard" section. This section contains list of assignments and +list of fellow students. If supervisors of groups allowed students to see each +others statistics there will also be points which particular students gained. In the "Assignments" box on the group detail page there is list of assigned exercises which students are supposed to solve. The assignments are displayed @@ -1943,7 +1943,7 @@ deadlines can be different. An assignment link will lead you to assignment detail page where are presented all known details about assignment. There are of course both deadlines, limit of submissions which you can make and also full-range description of assignment, -which can be localized. The localization can be ondemand switched between all +which can be localized. The localization can be on demand switched between all language variants in tab like box. Further on the page you can find "Submitted solutions" box where is a list of @@ -1968,9 +1968,9 @@ submitter name (supervisor can submit solution on your behalf), further there are files which were uploaded on submission and most importantly "Evaluation details" and "Test results" boxes. -Evalation details contains overall results of your solution. There are +Evaluation details contains overall results of your solution. There are information such as if solution was provided before deadlines, if the evaluation -process succesfully finished or if compilation succeeded. After that you can +process successfully finished or if compilation succeeded. After that you can find a lot of values, most important one is the last, "Total score", consisting of your score, slash and the maximum number of points for this assignment. Interestingly the your score value can be higher than the maximum, which is @@ -2019,7 +2019,7 @@ of the matching group box. ### Manage group Locate group you supervise and you want to manage. All your supervised groups -are available in sidebar under "Groups -- supervisor" collapsable menu. If you +are available in sidebar under "Groups -- supervisor" collapsible menu. If you click on one of those you will be redirected to group detail page. In addition to basic group information you can also see "Supervisor's controls" section. In this section there are lists of current students and assignments. @@ -2088,7 +2088,9 @@ In meta information form you can fill these options: can find some very simple one already in here, description of score configuration can be found further in "Writing score configuration" chapter - first submission deadline -- maximum gainable points before first deadline +- maximum gainable points before first deadline; if you want to manage all + points manually, set here 0 and then use concept of bonus points, which is + described in the next subchapter - second submission deadline, after that students still can submit exercises but no points for them (must be after the first deadline) - maximum gainable points after first deadline and before second deadline @@ -2121,24 +2123,42 @@ runtime environment and another nested tabbed box. In there you can find all hardware groups which are available for exercise and set limits for all test cases. The 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" items. If you are satisfied with changes you made to the limits, +test case then you can take a peek on collapsible "Reference solutions' +evaluations" items. If you are satisfied with changes you made to the limits, save form with "Change limits" button right under environments box. ### Students' solutions management -@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. - -@todo Can I assign points to my students’ solutions manually instead of depending on automatic scoring? If and how to change the score of a solution – assignment -settings, setting points, bonus points, accepting a solution (*not -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. - -@todo: Describe the comments thread behavior (public/private comments), -who else can see the comments -- same as from the student perspective +One of the most important tasks for a group supervisor is checking student +solutions. As automatic evaluation of them cannot catch all aspects of source +code, it is suitable to do a brief manual review of student's coding style and +reflect that in assignment bonus points. + +On "Assignment detail" page there is an "View student results" button near top +of the page (next to "Edit assignment settings" button). This will redirect you +to a page where is a list of boxes, one box per student. Each student box +contains a list of submissions for this assignment. The row structure of +submission list is the same as the structure in student's "Submitted solution" +box. More information about every solution can be showed by clicking on "Show +details" link on the end of solution row. + +This page is the same as for students with one exception -- there is an +additional collapsed box "Set bonus points". In unfolded state, there is an +input field for one number (positive or negative integer) and confirmation +button "Set bonus points". After filling intended amount of points and +submitting the form, the data in "Evaluation details" box get immedialely +updated. To remove assigned bonus points, submit just the zero number. The bonus +points are not additive, newer value overrides older values. + +It is useful to give a feedback about the solution back to the user. For this +can be nicely used the "Commens and notes" box. Make sure that the messages are +not private, so the student can see them. More detailed description of this box +is available in student part of user documentation. + +One of the discussed concept was marking one solution as accepted. However, due +to lack of frontend developers it is not yet prepared in user interface. We +hope, it will be ready as soon as possible. The button for accepting a solution +will be most propably also on this page. ### Creating exercises @@ -2183,7 +2203,7 @@ during execution according to job configuration. Files can be uploaded either by drag and drop mechanism or by standard "Add a file" button. In opened dialog window choose file which should be uploaded. All -chosen files are immediatelly uploaded to server but to save supplementary files +chosen files are immediately uploaded to server but to save supplementary files list you have to hit "Save supplementary files" button. All previously uploaded files are visible right under drag and drop area, please note that files are stored on fileserver and cannot be deleted after upload. @@ -2227,7 +2247,7 @@ get the up-to-date information). ## Group administrator Group administrator is the group supervisor with some additional permissions in -particular group. Namely group administator is capable of creating a subgroups +particular group. Namely group administrator is capable of creating a subgroups in managed group and also adding and deleting supervisors. Administrator of the particular group can be only one person. @@ -2239,7 +2259,7 @@ sidebar and choose the right group detail page. If you are there you can see "Administrator controls" section, here you can either add supervisor to group or create new subgroup. -Form for creatingi a subgroup is present right on the group detail page in "Add +Form for creating a subgroup is present right on the group detail page in "Add subgroup" box. Group can be created with following options: - name which will be visible in group hierarchy @@ -2268,35 +2288,35 @@ particular supervisor should not to be supervisor of the group anymore. ## Instance administrator -Administrator of instance can be only one per instance. In addition to previous -roles instance admin should be able to modify instance details, manage licences -and take care of groups which belong to instance. +Instance administrator can be only one person per instance. In addition to +previous roles this administrator should be able to modify the instance details, +manage licenses and take care of top level groups which belong to the instance. ### Instance management -List of all instances in system can be found under "Instances" link in sidebar. -On the mentioned page there is a table of instances with their respective -admins. If you are admin of one of them you can visit its page by clicking on -the instance name. On instance details page you can find some description of -instance, current groups hierarchy and form for creating new group. +List of all instances in the system can be found under "Instances" link in the +sidebar. On that page there is a table of instances with their respective +admins. If you are one of them, you can visit its page by clicking on the +instance name. On the instance details page you can find a description of the +instance, current groups hierarchy and a form for creating a new group. -If you want to change some of the instance settings follow "Edit instance" link -on instance details page. This will take you to instance editation page with -corresponding form. In there you can fill following information: +If you want to change some of the instance settings, follow "Edit instance" link +on the instance details page. This will take you to the instance editation page +with corresponding form. In there you can fill following information: - name of the instance which will be visible to every other user - brief description of instance and for whom it is intended - checkbox if instance is open or not which means public or private (hidden from - potentional users) + potential users) -If you are done with editation, save filled information by clicking on "Update -instance" button. +If you are done with your editation, save filled information by clicking on +"Update instance" button. -If we go back to the instance details page you can find here "Create new group" -box which is able to add group to instance. This form is the same as the one for -creating subgroup in already existing group so we can skip description of form -fields. After successful creation of group it should appear in "Groups -hierarchy" box at the top of the page. +If you go back to the instance details page you can find there a "Create new +group" box which is able to add a group to the instance. This form is the same +as the one for creating subgroup in already existing group so we can skip +description of the form fields. After successful creation of the group it will +appear in "Groups hierarchy" box at the top of the page. ### Licenses @@ -2305,29 +2325,29 @@ hierarchy" box at the top of the page. ## 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. +Superadministrator is a user with the most privileges and as such superadmin +should be quite a unique role. Ideally, there should be only one user 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 are only a few user roles 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, the administrator has to change the role for his/her account +manually in the database. 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. +Changing role from student to supervisor and back is done automatically when the +new privileges are granted to the user, so managing roles by hand in database is +not needed. Previously stated information can be applied to instances as well, +but instances can only have admins. Roles description: