reworked requirements section

8 years ago · 74a14d22a4
parent b5e2750e15
commit 74a14d22a4
1 changed files with 82 additions and 52 deletions
--- a/Rewritten-docs.md
+++ b/Rewritten-docs.md
@ -256,42 +256,69 @@ addons (mostly administrative features).

 #### End user requirements

- group hierarchy -- @todo: copy text from
-[here](https://github.com/ReCodEx/wiki/wiki/Rewritten-docs/87e4bcd39a4fca3eadbb4748e9a3b6ced2bd7150#intended-usage)
- there is a database of exercises; teachers can create exercises including
-  textual description, sample inputs and correct reference outputs (for example
-  "sum all numbers from given file and write the result to the standard output")
- teachers can specify way of computation grading points which will be awarded
-  to the students depending on the quality of his/her solution for each
-  assignment extra
- teachers can view detailed data about their students (users of a their groups)
-  including all submitted solutions; also, each of the solution can be manually
-  reviewed, commented and assigned additional points (positive or negative)
- one particular solution can be marked as accepted (used for grading this
-  assignment); otherwise, the solution with most points is used
- teacher can edit student solution and privately resubmit it; optionally saving
-  all results (including temporary ones)
- localization of all texts (UI and exercises)
- Markdown support for creating exercise texts
- tagging exercises in database and search by these tags
- comments of exercises, tests and solutions
- plagiarism detection
+- _group hierarchy_ -- creating an arbitrarily nested tree structure should be
+  supported to allow keeping related groups together, such as in the example
+  below. A group hierarchy also allows archiving data from past courses.
+
+```
+  Summer term 2016
+  |-- Language C# and .NET platform
+  |   |-- Labs Monday 10:30
+  |   `-- Labs Thursday 9:00
+  |-- Programming I
+  |   |-- Labs Monday 14:00
+  ...
+```
+
+- _a database of exercises_ -- teachers should be able to create exercises
+  including textual description, sample inputs and correct reference outputs
+  (for example "sum all numbers from given file and write the result to the
+  standard output") and to browse this database
+- _customizable grading system_ -- teachers need to specify the way of
+  computation of the final score, which will be awarded to the student's
+  submissions depending on their quality
+- _viewing student details_ -- teachers should be able to view detailed data
+  about their students (members of their groups), including all submitted
+  solutions;
+- _awarding additional points_ -- adding (or subtracting) points from the final
+  score of a submission by a supervisor must be supported
+- _marking a solution as accepted_ -- the system should allow marking one
+  particular solution as accepted (used for grading the assignment) by the
+  supervisor
+- _solution resubmission_ -- teachers should be able edit student's solutions
+  and privately resubmit them, optionally saving all results (including
+  temporary ones); this feature can be used to quickly fix errors in the
+  solution 
+- _localization_ -- all texts (UI and exercises) should be translatable
+- _formatted exercise texts_ -- Markdown or another lightweight markup language
+  should be supported for formatting exercise texts
+- _exercise tags_ -- the system should support tagging exercises searching by
+  these tags
+- _comments_ -- adding both private and public comments to exercises, tests and
+  solutions should be supported
+- _plagiarism detection_

 #### Administrative requirements

- users can use an intuitive user interface for interaction with the system,
-  mainly for viewing assigned exercises, uploading their own solutions to the
-  assignments, and viewing the results of the solutions after an automatic
-  evaluation is finished; the two wanted interfaces are web and command-line
-  based
- user privilege separation (at least two roles -- _student_ and _supervisor_)
- logging in through a university authentication system (e.g. LDAP)
- SIS (university information system) integration for fetching personal user
-  data
- safe environment in which the students' solutions are executed
- support for multiple programming environments at once to avoid unacceptable
-  workload for administrator (maintain separate installation for every course)
-  and high hardware occupation
+- _pluggable user interface_ -- the system should allow using an alternative
+  user interface, such as a command line client; implementation of such clients
+  should be as straightforward as possible
+- _privilege separation_ -- there should be at least two roles -- _student_ and
+  _supervisor_. Cases when a student of a course is also a teacher of another
+  lab must be handled correctly
+- _alternate authentication methods_ -- logging in through a university
+  authentication system (e.g. LDAP) and potentially other services, such as
+  OAuth, should be supported
+- _querying SIS_ -- loading user data from the university information system
+  should be supported
+- _sandboxing_ -- there should be a safe environment in which the students'
+  solutions are executed to prevent system failures due to malicious code being
+  submitted; the sandboxed environment should have the least possible impact on
+  measurement results (most importantly on measured times)
+- _heterogenous worker pool_ -- there must be support for submission evaluation
+  in multiple programming environments in a single installation to avoid
+  unacceptable workload for the administrator (maintaining a separate
+  installation for every course) and high hardware occupation
 - advanced low-level evaluation flow configuration with high-level abstraction
  layer for ordinary configuration cases; the configuration should be able to
  express more complicated flows than just compiling a source code and running
@ -303,33 +330,36 @@ addons (mostly administrative features).
 ### Non-functional requirements

 Non-functional requirements are requirements of technical character with no
-direct mapping to visible parts of system. In ideal word, users should not know
-about these if they work properly, but would be at least annoyed if these
-requirements were not met. Most notably they are these ones:
-
- user interface of the system accessible on users' computers without
-  installation of any kind of additional software
- easy implementation of different user interfaces
- be ready for workload hundreds of students and tens of supervisors
- automated installation of all components
- source code with permissive license allowing further development; this also
-  applies on used libraries and frameworks
- multi-platform worker supporting at least two major operating systems
+direct mapping to visible parts of the system. In an ideal world, users should
+not know about these features if they work properly, but would be at least
+annoyed if they did not. 
+
+- _no installation_ -- the primary user interface of the system must be accessible
+  on users' computers without the need to install any additional software
+- _performace_ -- the system must be ready for at least hundreds of students and
+  tens of supervisors using it at once
+- _automated deployment_ -- all of the components of the system must be easy to
+  deploy in an automated fashion
+- _open source licensing_ -- the source code should be released under a
+  permissive license allowing further development; this also applies to used
+  libraries and frameworks
+- _multi-platform worker_ -- worker machines running Linux, Windows and
+  potentially other operating systems must be supported

 ### Conclusion

 The survey shows that there are a lot of different requirements and wishes for
-the new system. When the system is ready it is likely that there will be new
+the new system. When the system is ready, it is likely that there will be new
 ideas of how to use the system and thus the system must be designed to be easily
-extendable, so everyone can develop their own feature.  This also means that
-widely used programming languages and techniques should be used, so users can
-quickly understand the code and make changes.
-
+extendable, so that these new ideas can be easily implemented, either by us or
+community members. This also means that widely used programming languages and
+techniques should be used, so that users can quickly understand the code and
+make changes.

 ## Related work

-To find out the current state in the field of automatic grading systems we did a
-short market survey on the field of automatic grading systems at universities,
+To find out the current state in the field of automatic grading systems, we did
+a short market survey on the field of automatic grading systems at universities,
 programming contests, and possibly other places where similar tools are
 available.