diff --git a/Rewritten-docs.md b/Rewritten-docs.md index bfe0c6b..0907159 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1755,24 +1755,23 @@ modern web applications. # User documentation Users interact with the ReCodEx through the web application. It is required to -use a modern web browser with good HTML5 and CSS3 support. Among others cookies +use a modern web browser with good HTML5 and CSS3 support. Among others, cookies and local storage are used. Also a decent JavaScript runtime must be provided by the browser. Supported and tested browsers are: Firefox 50+, Chrome 55+, Opera 42+ and Edge -13+. Mobile devices often have problems with internalization and possibly lack -support for some common features of desktop browsers. For us in this stage of -development is not possible to fine tune the interface for major mobile browsers -on all mobile platforms. However, it is confirmed to work with latest Google -Chrome and Gello browser on Android 7.1+. There are reported some issues with -Firefox which may be fixed in future. Also, it is confirmed working with Safari -browser on iOS 10. - -Usage of the web application is divided into the sections concerning the -particular user roles. Under these sections all possible use cases can be found. -These sections are inclusive, so more privileged users need to know stuff from -all less or equal privileged sections than their level of privilege. -Described roles are: +13+. Mobile devices often have problems with internationalization and possibly +lack support for some common features of desktop browsers. In this stage of +development is not possible for us to fine tune the interface for major mobile +browsers on all mobile platforms. However, it is confirmed to work with latest +Google Chrome and Gello browser on Android 7.1+. Issues have been reported with +Firefox that will be fixed in the future. Also, it is confirmed to work with +Safari browser on iOS 10. + +Usage of the web application is divided into sections concerning particular user +roles. Under these sections all possible use cases can be found. These sections +are inclusive, so more privileged users need to read instructions for all less +privileged users. Described roles are: - Student - Group supervisor @@ -1822,26 +1821,26 @@ application follows. ### First steps in ReCodEx -You can create an account if you click on the "*Create account*" menu item in +You can create an account by clicking the "*Create account*" menu item in the left sidebar. You can choose between two types of registration methods -- by creating a local account with a specific password, or pairing your new account with an existing CAS UK account. -If you decide a new "*local*" account using the "*Create ReCodEx account*” form, -you will have to provide your details and choose a password for your account. -Although ReCodEx allows using quite weak passwords, it is wise to use a bit -stronger ones. The actual strength is shown in progress bar near the password -field during registration. You will later sign in using your email address as -your username and the password you select. +If you decide to create a new "*local*" account using the "*Create ReCodEx +account*” form, you will have to provide your details and choose a password for +your account. Although ReCodEx allows using quite weak passwords, it is wise to +use a bit stronger ones The actual strength is shown in progress bar near the +password field during registration. You will later sign in using your email +address as your username and the password you select. -If you decide to use the CAS UK, then ReCodEx will verify your CAS credentials -and create a new account based on information stored there (name and email -address). You can change your personal information later on the "*Settings*" -page. +If you decide to use the CAS UK service, then ReCodEx will verify your CAS +credentials and create a new account based on information stored there (name and +email address). You can change your personal information later on the +"*Settings*" page. -When creating the account both ways, an instance the account will belong to must -be selected. The instance will be most likely your university or other -organization you are a member of. +Regardless of the desired account type, an instance it will belong to must be +selected. The instance will be most likely your university or other organization +you are a member of. 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 of the two forms @@ -1861,24 +1860,25 @@ There are several options you can edit in your user account: You can access the settings page through the "*Settings*" button right under your name in the left sidebar. -If you do not use ReCodEx for a whole day, you will be logged out automatically. -However, we recommend you sign out of the application after you finished your -interaction with it. The logout button is placed in the top section of the left -sidebar right under your name. You may need to expand the sidebar with a button -next to the "*ReCodEx*” title (also known as _hamburger button_). +If you are not active in ReCodEx for a whole day, you will be logged out +automatically. However, we recommend you sign out of the application after you +finish your interaction with it. The logout button is placed in the top section +of the left sidebar right under your name. You may need to expand the sidebar +with a button next to the "*ReCodEx*” title (informally known as _hamburger +button_), depending on your screen size. ### Forgotten password If you cannot remember your password and you do not use CAS UK authentication, then you can reset your password. You will find a link saying "Cannot remember what your password was? Reset your password." under the sign in form. After you -click on this link, you will be asked to submit your registration email address. -A message with a link containing a special token will be sent to your address. -We make sure that the person who requested password resetting is really you. -When you click on the link (or you copy & paste it into your web browser) you -will be able to select a new password for your account. The token is valid only -for a couple of minutes, so do not forget to reset the password as soon as -possible, or you will have to request a new link with a valid token. +click this link, you will be asked to submit your registration email address. A +message with a link containing a special token will be sent to you by e-mail -- +we make sure that the person who requested password resetting is really you. +When you visit the link, you will be able to enter a new password for your +account. The token is valid only for a couple of minutes, so do not forget to +reset the password as soon as possible, or you will have to request a new link +with a valid token. If you sign in through CAS UK, then please follow the instructions provided by the administrators of the service described on their @@ -1887,16 +1887,16 @@ website. ### Dashboard When you log into the system you should be redirected to your "*Dashboard*". On -this page according to your role in system you can see some brief information -about the groups you are member of. Further description of dashboard will be -provided later on with according roles. +this page you can see some brief information about the groups you are member of. +The information presented there varies with your role in the system -- further +description of dashboard will be provided later on with according roles. ## Student Student is a default role for every newly registered user. This role has quite -limited range what can to do in ReCodEx. Generally student can only submit -solutions of exercises in some particular groups. These groups should correspond -to courses he/she attend at college. +limited capabilites in ReCodEx. Generally, a student can only submit solutions +of exercises in some particular groups. These groups should correspond to +courses he/she attends. On the "*Dashboard*" page there is "Groups you are student of" section where you can find list of your student groups. In first column of every row there is a @@ -1909,17 +1909,16 @@ provided "Show group's detail" button. ### Join group and start solving assignments -To be able to submit solutions you have to be member of the right group. Each -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. +To be able to submit solutions you have to be a member of the right group. Each +instance has its own group hierarchy, so you can choose only those within your +instance. That is why a list of groups is available from under an instance link +located in the sidebar. This link brings you to instance detail page. 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 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. +further extended. When you find a group you would like to join, continue by +clicking on "See group's page" link following with "Join group" link. **Note:** Some groups can be marked as private and these groups are not visible in hierarchy and membership cannot be established by students themselves. @@ -1927,17 +1926,17 @@ 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 +supervisors and also hierarchy of subgroups. Most importantly, there is the "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. +a list of fellow students. If supervisors of groups allowed students to see each +other's statistics there will also be the number of points the students gained. -In the "Assignments" box on the group detail page there is list of assigned +In the "Assignments" box on the group detail page there is a list of assigned exercises which students are supposed to solve. The assignments are displayed with their names and deadlines. There are possibly two deadlines, the first one means that till this datetime student will receive full amount of points in case -of successful solution. Second deadline does not have to be set, but in case of -presence the maximum number of points for successful solution between these two +of successful solution. Second deadline does not have to be set, but in case it +is, the maximum number of points for successful solution between these two deadlines can be different. An assignment link will lead you to assignment detail page where are presented @@ -1953,28 +1952,28 @@ to submit solution of the assignment. After clicking on submit button, dialog window will show up. In here you can upload files representing your solution, you can even add some notes to mark the -solution. Your supervisor can also access the note. After you successfully -uploaded all files necessary for your solution, click on "Submit your solution" -button and let ReCodEx do its thing. +solution. Your supervisor can also access this note. After you successfully +upload all files necessary for your solution, click the "Submit your solution" +button and let ReCodEx evaluate the solution. During the execution ReCodEx backend might send evaluation progress state to your browser which will be displayed in another dialog window. When the whole execution is finished then a "See the results" button will appear and you can look at the results of your solution. -On the results detail page there are a lot of information. Apart assignment -description which is not connected to your results there is also the solution -submitter name (supervisor can submit solution on your behalf), further there +On the results detail page there are a lot of information. Apart from assignment +description, which is not connected to your results, there is also the solution +submitter name (supervisor can submit a solution on your behalf), further there are files which were uploaded on submission and most importantly "Evaluation details" and "Test results" boxes. Evaluation details contains overall results of your solution. There are -information such as if solution was provided before deadlines, if the evaluation -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 -caused by "Bonus points" item above. If your solution is nice and +information such as whether the solution was provided before deadlines, if the +evaluation 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 caused by "Bonus points" item above. If your solution is nice and supervisor notices it, he/she can assign you additional points for effort. On the other hand, points can be also subtracted for bad coding habits or even cheating. @@ -2004,10 +2003,10 @@ mechanism for new comment messages. ## Group supervisor -Group supervisor is ordinarily the lecturer of the corresponding course. With -this role user can modify group description and properties, assign exercises or -manage list of students. Further permissions like managing subgroups or -supervisors is available only for group administrators. +Group supervisor is typically the lecturer of a course. A user in this role can +modify group description and properties, assign exercises or manage list of +students. Further permissions like managing subgroups or supervisors is +available only for group administrators. On "Dashboard" page you can find "Groups you supervise" section. Here there are boxes representing your groups with the list of students attending course and @@ -2029,7 +2028,8 @@ at the top of the page. Following this link will take you to group editation page with form containing these fields: - group name which is visible to other users -- external identification which may be used for ID from school system +- external identification which may be used for pairing with entries in an + information system - description of group which will be available to users in instance (in Markdown) - set if group is publicly visible (and joinable by students) or private @@ -2043,7 +2043,7 @@ group" button and all changes will be applied. For students management there are "Students" and "Add student" boxes. The first one is simple list of all students which are attending the course with the possibility of delete them from the group. That can be done by hitting "Leave -group" button near particular user. Second box serves to adding students to the +group" button near particular user. The second box is for adding students to the group. There is a text field for typing name of the student and after clicking on the magnifier image or pressing enter key there will appear list of matched users. At this moment just click on the "Join group" button and student will be @@ -2051,8 +2051,8 @@ signed in to your group. ### Assigning exercises -Before assigning exercise you obviously have to know what exercises are -available. List of all exercises in the system can be found under "Exercises" +Before assigning an exercise, you obviously have to know what exercises are +available. A list of all exercises in the system can be found under "Exercises" link in sidebar. This page contains a table with exercises names, difficulties and names of the exercise authors. Further information about exercise is available by clicking on its name. @@ -2065,9 +2065,9 @@ where some important information can be found. And most notably there is an information about available programming languages for this exercise, under "Supported runtime environments" section. -If you decide that the exercise is suitable for any of your groups, please note +If you decide that the exercise is suitable for one of your groups, look for the "Groups" box at the bottom of the page. There is a list of all groups you -supervise with quick "Assign" button which will assign the exercise to the +supervise with an "Assign" button which will assign the exercise to the selected group. After clicking on the "Assign" button you should be redirected to assignment @@ -2077,10 +2077,10 @@ 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 a group -- visibility, if assignment is under construction then you can mark it as not - visible and students will not see it +- visibility (if an 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 + on "Add language variant" button, current one can be deleted with "Remove this language" button) - language of description from dropdown field (english, czech, german) - description in selected language @@ -2088,21 +2088,21 @@ 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; if you want to manage all - points manually, set here 0 and then use concept of bonus points, which is +- maximum points that can be gained before the first deadline; if you want to + manage all points manually, set it to 0 and then use bonus points, which are 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 -- submission count limit for students' solutions, after this amount students - cannot submit solutions any more -- visibility of memory and time ratios; if true students can see percentage of - used memory and time for each test -- minimum percentage of points which each submission have to gain otherwise it - will gain no points -- assignment is marked as bonus one and points from solving it are not included - into group threshold limit (that means solving it can get you additional - points over the limit) + they are given no points no points (must be after the first deadline) +- maximum points that can be gained between first deadline and second deadline +- submission count limit for students' solutions -- limits the amount of + attempts a student has at solving the problem +- visibility of memory and time ratios; if true students can see the percentage + of used memory and time (with respect to the limit) for each test +- minimum percentage of points which each submission must gain to be considered + correct (if it gets less, it will gain no points) +- whether the assignment is marked as bonus one and points from solving it are + not included into group threshold limit (that means solving it can get you + additional points over the limit) The form has to be submitted with "Edit settings" button otherwise changes will not be saved. @@ -2112,27 +2112,27 @@ only creation. That is why on 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 not to use one of those, locate "Remove" button at the bottom of the -box tab which will delete this environment from the assignment. Please note that -this action is irreversible. +The last unexplored area is the time and memory limits form. The whole form is +situated in a box with tabs which are leading to particular runtime +environments. If you wish not to use one of those, locate "Remove" button at the +bottom of the box tab which will delete this environment from the assignment. +Please note that this action is irreversible. -In general one tab in environments box contains some basic information about +In general, every 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 set limits for all test +hardware groups which are available for the 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 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. +save the form with "Change limits" button right under environments box. ### Students' solutions management -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. +One of the most important tasks of a group supervisor is checking student +solutions. As automatic evaluation of them cannot catch all problems in the +source code, it is advisable 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 @@ -2151,8 +2151,8 @@ 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 +you can use the "Commens and notes" box. Make sure that the messages are not +private, so that 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 @@ -2228,7 +2228,7 @@ runtime configurations" button. If you want to delete some particular runtime just hit "Remove" button in the right tab, please note that after this operation runtime configurations form has to be again saved to apply changes. -All runtime configurations which was added to exercise will be visible to +All runtime configurations which were added to exercise will be visible to supervisors and all can be used in assignment, so please be sure that all of the languages and job configurations are working. @@ -2245,7 +2245,7 @@ solution are displayed in yellow boxes under forms for setting assignment limits as described earlier. However, there is curretly no user interface to upload and evaluate reference -solutions. It is possible to use direct REST API calls, but it is not much user +solutions. It is possible to use direct REST API calls, but it is not very user friendly. If you are interested, please look at [API documentation](https://recodex.github.io/api/), notably sections _Uploaded-Files_ and _Reference-Exercise-Solutions_. You need to upload the @@ -2253,8 +2253,8 @@ reference solution files, create a new reference solution and then evaluate the solution. After that, measured data will be available in the box at assignment editing page (setting limits section). -We are now working on better user interface, which will be available soon. Then -the description will be added here. +We are now working on a better user interface, which will be available soon. +Then its description will be added here. ## Group administrator @@ -2383,16 +2383,16 @@ Roles description: 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. + user in ReCodEx who should be able to do access any functionality provided by + the application. ## Writing score configuration -Important thing about assignment is how to assign points to particular -solutions. As mentioned previously whole job is composed of logical tests. All -of these tests have to contain one essential "evaluation" task. Evaluation task -should output one float number which can be further used for scoring of +An important thing about assignment is how to assign points to particular +solutions. As mentioned previously, the whole job is composed of logical tests. +All of these tests have to contain one essential "evaluation" task. Evaluation +task should output one float number which can be further used for scoring of particular tests. Total resulting score of the students solution is then calculated according to a @@ -2401,11 +2401,11 @@ score is also a float between 0 and 1. This number is then multiplied by the maximum of points awarded for the assignment by the teacher assigning the exercise -- not the exercise author. -For now there is only one way how to write score configuration using only simple -score calculator. But the implementation in API is agile enough to handle +For now, there is only one way how to write score configuration using only +simple score calculator. But the implementation in API is agile enough to handle upcoming score calculators which might use some more complex scoring algorithms. -This also means that future calculators do not have to use YAML format as the -already defined one, but can use its own or different one. +This also means that future calculators do not have to use the YAML format for +configuration. In fact, the configuration can be a string in any format. ### Simple score calculation