Documentation: Add user guide (#247)

ls1intum · Nov 20, 2023 · bcc2e19 · bcc2e19
1 parent 4302fba
commit bcc2e19
Show file tree

Hide file tree

Showing 30 changed files with 305 additions and 5 deletions.
diff --git a/docs/admin/issues.rst b/docs/admin/issues.rst
@@ -1,8 +1,7 @@
 Known Issues and Workarounds 
 ===========================================
 .. TODO: Remove once Athena is fully integrated
-*The information below will be removed once feedback suggestions are completely integrated into
-Artemis.*
+.. note:: *This section will be removed once feedback suggestions are completely integrated into Artemis.*
 
 The feedback suggestion server ThemisML currently only works with Java projects.
 This should be easy to fix by creating an ANTLR grammar for every additional language to support and configuring the codeBERT similarity comparison accordingly.

diff --git a/docs/app-icon.png b/docs/app-icon.png
diff --git a/docs/contributor/system-design/access-control.rst b/docs/contributor/system-design/access-control.rst
@@ -1,7 +1,7 @@
 .. _Access Control and Security:
 
 Access Control and Security
---------------------------
+---------------------------
 
 .. Access control and security describes the user model of the system in terms of an access matrix. This section also describes security issues, such as the selection of an authentication mechanism, the use of encryption, and the management of keys. This section is optional. It should be included if the non-functional requirements include security concerns. For details refer to section 7.4.3 in Prof. Bruegge's book.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,14 +3,21 @@
 ======================================================
 Themis: Artemis Tutor App for iPad
 ======================================================
-.. TODO: Add icon
+
+.. figure:: /app-icon.png
+    :align: center
+    :alt: App Icon
+    :width: 12%
+
+\
+
 Themis is an innovative iPad app providing a comprehensive and optimized way for tutors to assess student submissions
 on the go. As a complementary extension to the `Artemis <https://docs.artemis.cit.tum.de/>`_ platform,
 an open-source learning management system used at universities, Themis allows tutors to effortlessly
 inspect students' submissions and provide feedback.
 
 Designed as a native iPad application, Themis optimizes viewing and assessing exercises on a mobile
-device. Its' intuitive interface and user-friendly assessment editor enable tutors to give general as well as
+device. Its intuitive interface and user-friendly assessment editor enable tutors to give general as well as
 referenced feedback for programming, text, modeling, and file upload exercises. Leveraging the iPad's unique features
 allows a more convenient and streamlined feedback process using Themis. By supporting the Apple Pencil, tutors can
 highlight specific segments and provide comments using the Scribble feature.
@@ -21,6 +28,14 @@ providing feedback suggestions. By analyzing submissions and comparing past feed
 suggestions fitting to current submissions are proposed. The suggestions are displayed for tutors to review and modify
 as needed, improving the accuracy and efficiency of the assessment process.
 
+.. toctree::
+    :caption: User Guide
+    :includehidden:
+    :maxdepth: 2
+
+    user/login/login
+    user/assessment-overview/assessment-overview
+
 .. toctree::
     :caption: Contributor Guide
     :includehidden:

diff --git a/docs/user/assessment-overview/assessment-overview.rst b/docs/user/assessment-overview/assessment-overview.rst
@@ -0,0 +1,132 @@
+Assessment
+==========
+
+Assess Exercises
+----------------
+After login, you will be redirected to the course view, where you can select a course and 
+view exercises. You can find more information about this view in the following video:
+
+.. raw:: html
+
+	<iframe src="https://live.rbg.tum.de/w/artemisintro/40508?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="500">
+		Course view tutorial
+	</iframe>
+
+By tapping on an exercise in the course view you can navigate to a new screen where exercise
+details are shown. From here, you can start a new assessment, or manage ongoing assessments.
+
+.. raw:: html
+
+	<iframe src="https://live.rbg.tum.de/w/artemisintro/40568?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="500">
+		Exercise view tutorial
+	</iframe>
+
+Themis supports the assessment of the following exercise types:
+
+.. toctree::
+	:maxdepth: 1
+
+	/user/programming-assessment/programming-assessment
+	/user/text-assessment/text-assessment
+	/user/modeling-assessment/modeling-assessment
+	/user/file-upload-assessment/file-upload-assessment
+
+General Assessment Elements
+---------------------------
+The assessment view of Themis contains some elements that are common for all exercise types.
+
+Toolbar
+^^^^^^^
+.. figure:: ./images/toolbar.png
+    :align: center
+    :alt: Assessment View Toolbar
+    :width: 85%
+
+    Assessment View Toolbar
+
+1. **Cancel Button** - allows you to cancel the assessment either by deleting or saving the current state
+2. **Exercise Name Label** - indicates the name of the exercise that you are currently assessing
+3. **Undo Button** - allows you to undo the last operation that you have done
+4. **Redo Button** - allows you to redo the last operation that you have done
+5. **Referenced Feedback Mode Button** - when enabled, allows you to add referenced (inline) feedback
+6. **Font Size Button** - allows changing the font size
+7. **Score Label** - shows the current score of the submission
+8. **Save Button** - saves the current state of the assessment
+9. **Submit Button** - submits the assessment
+
+Correction Pane
+^^^^^^^^^^^^^^^
+The correction pane can be dragged from the right to view the problem statement,
+correction guidelines, and an overview of feedback added to the submission. All
+three states of the correction pane can be seen below:
+
+.. figure:: ./images/correction-sidebar.png
+	:width: 85%
+	:align: center
+
+	Correction Pane
+
+General feedback can be added with the |plus-btn| button. This button reveals a 
+sheet where you can type the feedback text, adjust the score, and select a grading 
+criterion:
+
+.. figure:: ./images/add-feedback-sheet.png
+	:width: 40%
+	:align: center
+
+	Add Feedback Sheet
+
+You can edit feedback by tapping on the |edit-btn| button on the correction pane.
+
+In order to delete an existing feedback, swipe it to the left on the correction pane 
+as shown below:
+
+.. figure:: ./images/feedback-removal.png
+	:width: 30%
+	:align: center
+
+	Swipe-To-Delete Action
+
+.. |edit-btn| image:: ./images/edit-btn.png
+   :width: 25px
+
+.. |plus-btn| image:: ./images/plus-btn.png
+   :width: 25px
+
+
+Assess Exam Exercises
+---------------------
+
+Themis supports the assessment of exam exercises as well. To assess an exam exercise, 
+navigate to the relevant exam from the course view and select the exercise that you want 
+to assess.
+
+|pic1| → |pic2|
+
+.. |pic1| image:: ./images/course-view-exam-selection.png
+   :width: 50%
+
+.. |pic2| image:: ./images/exam-exercise-selection.png
+   :width: 45%
+
+If the second correction round is enabled and all submissions for the first round are assessed, 
+the **Start Assessment** button changes into **Start Assessment (Round 2)**. In addition, 
+the **Open Submissions (Correction Round 2)** and **Finished Submissions (Correction Round 2)** 
+sections appear.
+
+.. figure:: ./images/2nd-round-exercise-view.png
+    :align: center
+    :alt: Exercise View in Second Correction Round
+    :width: 85%
+
+    Exercise View in Second Correction Round
+
+When performing an assessment in the second round, the assessment view toolbar contains a **Round 2** 
+label.
+
+.. figure:: ./images/2nd-round-assessment-view.png
+    :align: center
+    :alt: Assessment View in Second Correction Round
+    :width: 85%
+
+    Assessment View in Second Correction Round
diff --git a/docs/user/assessment-overview/images/2nd-round-assessment-view.png b/docs/user/assessment-overview/images/2nd-round-assessment-view.png
diff --git a/docs/user/assessment-overview/images/2nd-round-exercise-view.png b/docs/user/assessment-overview/images/2nd-round-exercise-view.png
diff --git a/docs/user/assessment-overview/images/add-feedback-sheet.png b/docs/user/assessment-overview/images/add-feedback-sheet.png
diff --git a/docs/user/assessment-overview/images/correction-sidebar.png b/docs/user/assessment-overview/images/correction-sidebar.png
diff --git a/docs/user/assessment-overview/images/course-view-exam-selection.png b/docs/user/assessment-overview/images/course-view-exam-selection.png
diff --git a/docs/user/assessment-overview/images/edit-btn.png b/docs/user/assessment-overview/images/edit-btn.png
diff --git a/docs/user/assessment-overview/images/exam-exercise-selection.png b/docs/user/assessment-overview/images/exam-exercise-selection.png
diff --git a/docs/user/assessment-overview/images/feedback-mode-btn.png b/docs/user/assessment-overview/images/feedback-mode-btn.png
diff --git a/docs/user/assessment-overview/images/feedback-removal.png b/docs/user/assessment-overview/images/feedback-removal.png
diff --git a/docs/user/assessment-overview/images/plus-btn.png b/docs/user/assessment-overview/images/plus-btn.png
diff --git a/docs/user/assessment-overview/images/toolbar.png b/docs/user/assessment-overview/images/toolbar.png
diff --git a/docs/user/file-upload-assessment/file-upload-assessment.rst b/docs/user/file-upload-assessment/file-upload-assessment.rst
@@ -0,0 +1,37 @@
+File Upload Exercise
+====================
+.. raw:: html
+
+	<iframe src="https://live.rbg.tum.de/w/artemisintro/41039?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="500">
+		File upload exercise assessment tutorial
+	</iframe>
+
+.. note::
+	File upload exercises do **not** support referenced feedback.
+
+The following **file extensions** are supported by Themis and can be viewed without leaving 
+the app:
+
+- pdf
+- jpeg
+- png
+- doc
+- docx
+- xlsx
+- txt
+- csv
+
+If a submission contains an unsupported file, you can download the file and export it 
+to another app to view:
+
+.. figure:: ./images/file-upload-unsupported.png
+	:width: 60%
+	:align: center
+
+	Unsupported File Upload Exercise Submission
+
+.. figure:: ./images/file-upload-unsupported-export.png
+	:width: 60%
+	:align: center
+
+	Exporting Unsupported File Upload Exercise Submission
diff --git a/docs/user/file-upload-assessment/images/file-upload-unsupported-export.png b/docs/user/file-upload-assessment/images/file-upload-unsupported-export.png
diff --git a/docs/user/file-upload-assessment/images/file-upload-unsupported.png b/docs/user/file-upload-assessment/images/file-upload-unsupported.png
diff --git a/docs/user/login/images/uni-selection.png b/docs/user/login/images/uni-selection.png
diff --git a/docs/user/login/login.rst b/docs/user/login/login.rst
@@ -0,0 +1,13 @@
+Login
+=====
+
+You can log in to Themis using your Artemis credentials. You can select your university 
+using the **Select University** button. By default, TUM will be selected. Your selection 
+will be saved for subsequent app launches.
+
+.. figure:: ./images/uni-selection.png
+    :align: center
+    :alt: Login View
+    :width: 95%
+
+    Login View
diff --git a/docs/user/modeling-assessment/images/modeling-suggestions.png b/docs/user/modeling-assessment/images/modeling-suggestions.png
diff --git a/docs/user/modeling-assessment/modeling-assessment.rst b/docs/user/modeling-assessment/modeling-assessment.rst
@@ -0,0 +1,29 @@
+Modeling Exercise
+=================
+.. raw:: html
+
+	<iframe src="https://live.rbg.tum.de/w/artemisintro/41038?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="500">
+		Modeling exercise assessment tutorial
+	</iframe>
+
+When the referenced feedback mode (|feedback-mode-btn|) is enabled, you can tap on 
+the model elements to specify the part of the model you are referring to.
+
+.. |feedback-mode-btn| image:: ../assessment-overview/images/feedback-mode-btn.png
+   :width: 25px
+
+Feedback Suggestions
+--------------------
+Themis shows feedback suggestions for modeling exercises when available. The suggestions are shown 
+as light blue highlights on model elements. 
+
+.. figure:: ./images/modeling-suggestions.png
+	:width: 60%
+	:align: center
+
+	Modeling Submission With Suggestions (blue)
+
+You can tap on the highlighted elements to edit or reject suggestions. 
+
+.. note::
+	By default, all suggestions are automatically applied.
diff --git a/docs/user/programming-assessment/images/code-editor.png b/docs/user/programming-assessment/images/code-editor.png
diff --git a/docs/user/programming-assessment/images/file-tree.png b/docs/user/programming-assessment/images/file-tree.png
diff --git a/docs/user/programming-assessment/programming-assessment.rst b/docs/user/programming-assessment/programming-assessment.rst
@@ -0,0 +1,34 @@
+Programming Exercise
+====================
+.. raw:: html
+
+	<iframe src="https://live.rbg.tum.de/w/artemisintro/40962?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="500">
+		Programming exercise assessment tutorial
+	</iframe>
+
+While assessing programming exercises, you can browse the student, solution, and template 
+repositories using the file tree pane located on the left side of the screen:
+
+.. figure:: ./images/file-tree.png
+	:width: 16%
+	:align: center
+
+	File Tree (Left Pane)
+
+.. note:: You cannot add new referenced feedback or edit existing feedback while browsing the 
+	solution and template repositories.
+
+The content of the selected file is shown in the central pane. Green highlights 
+indicate the changed and added lines as shown below:
+
+.. figure:: ./images/code-editor.png
+	:width: 60%
+	:align: center
+
+	Code View (Middle Pane)
+
+When the referenced feedback mode (|feedback-mode-btn|) is enabled, you can drag 
+your finger over the code to highlight the specific part you are referring to.
+
+.. |feedback-mode-btn| image:: ../assessment-overview/images/feedback-mode-btn.png
+   :width: 25px
diff --git a/docs/user/text-assessment/images/correction-suggestions.png b/docs/user/text-assessment/images/correction-suggestions.png
diff --git a/docs/user/text-assessment/images/suggestion-review.png b/docs/user/text-assessment/images/suggestion-review.png
diff --git a/docs/user/text-assessment/images/text-suggestions.png b/docs/user/text-assessment/images/text-suggestions.png
diff --git a/docs/user/text-assessment/text-assessment.rst b/docs/user/text-assessment/text-assessment.rst
@@ -0,0 +1,41 @@
+Text Exercise
+=============
+.. raw:: html
+
+	<iframe src="https://live.rbg.tum.de/w/artemisintro/40925?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="500">
+		Text exercise assessment tutorial
+	</iframe>
+
+Similar to programming exercise assessments, when the referenced feedback mode (|feedback-mode-btn|) 
+is enabled, you can drag your finger or the Apple Pencil over the text to highlight the specific part you are referring to.
+
+.. |feedback-mode-btn| image:: ../assessment-overview/images/feedback-mode-btn.png
+   :width: 25px
+
+Feedback Suggestions
+--------------------
+Themis shows feedback suggestions for text exercises when available. The suggestions are shown 
+as colored underlines. 
+
+.. figure:: ./images/text-suggestions.png
+	:width: 80%
+	:align: center
+
+	Feedback Suggestions on Text
+
+You can tap on the underlines to edit or reject suggestions. 
+
+.. note::
+	By default, all suggestions are automatically applied.
+
+.. figure:: ./images/suggestion-review.png
+	:width: 50%
+	:align: center
+
+	Suggestion Review Sheet
+
+.. figure:: ./images/correction-suggestions.png
+	:width: 20%
+	:align: center
+
+	Feedback Suggestions on the Correction Pane