Development: Add documentation for standardized competencies

docs/user/adaptive-learning.rst

@@ -3,113 +3,23 @@
 Adaptive Learning
 =================
 
-.. contents:: Content of this document
-    :local:
-    :depth: 2
-
-Overview
---------
-Artemis allows students and instructors to define and track competencies, which are overarching learning objectives that tie together various lectures and exercises. Adaptive Learning in Artemis is centered around these competencies, allowing users to customize their learning experience and objectives. Furthermore, Artemis is able to provide students with individualized learning paths based on these competencies and their relations.
-
-Competencies
-------------
-
-Competencies for Students
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Competencies allow students to understand the learning goals of the course and measure their progress toward achieving them.
-
-In Artemis, a competency is considered mastered by a student when they complete all linked learning objects (progress equals 100%) and have an adequate confidence level (average score greater or equal to the mastery threshold set by the instructor).
-
-In case competencies are defined, students can get an overview of their individual progress and confidence on the competencies tab.
-The page lists all competencies with their title, description, and `taxonomy <https://en.wikipedia.org/wiki/Bloom%27s_taxonomy>`_.
-
-Expanding the prerequisites section shows the student all competencies from previous courses the instructor has selected as a prerequisite for this course.
-
-|students-learning-goals-statistics|
-
-When clicking on a competency, a page opens and displays detailed statistics about the competency together with all linked lecture units and exercises.
-The tripartite rings show the student's advancement:
-The **blue ring describes the progress**, the percentage of completed lecture units and exercises.
-The **green ring visualizes the confidence**, the average score in all linked exercises in relation to the threshold required for mastering the competency (set by the instructor).
-The **red ring is a weighted metric of the student's progress and confidence**, which shows the overall advancement toward competency mastery.
-
-|students-learning-goals-statistics-detail|
-
-Competencies for Instructors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Instructors have the ability to define competencies for a course, linking various lectures and exercises together under overarching learning objectives. They also have the ability to set the mastery threshold for these competencies.
-
-Competencies are overarching learning objectives that link together different course materials.
+Adaptive Learning in Artemis is centered around **competencies**, overarching learning objectives that tie together various lectures and exercises. Artemis is also able to provide students with individualized **learning paths** based on competencies and their relations.
 
 .. raw:: html
 
     <iframe src="https://live.rbg.tum.de/w/artemisintro/26313?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="350">
         Watch this video on TUM-Live.
     </iframe>
 
-An instructor can view and edit all competencies of a course on the competency management page.
-The table shows the title, description, and percentage of students that mastered the respective competency.
-
-On a side note, instructors can also select competencies from previous courses they taught as a prerequisite for this course.
-Students can see these on the competencies page and during the course self-registration.
-
-|instructors-learning-goals-manage|
-
-An instructor can create or edit competencies using the following form.
-Besides a title and description, they can optionally set a `taxonomy <https://en.wikipedia.org/wiki/Bloom%27s_taxonomy>`_.
-The mastery threshold describes the minimum average score required for a student to reach 100% confidence in this competency.
-The current average score of all linked exercises shown on this page can be used as a basis for defining a reasonable threshold value.
-Instructors can link competencies to lecture units on this page by first choosing a lecture and then selecting desired lecture units.
-
-|instructors-learning-goal-edit|
-
-Alternatively, instructors can also link competencies to an exercise or lecture unit on the respective management page using the selection box shown below.
-
-|instructors-learning-goals-link|
-
-Learning Paths
---------------
-
-Learning Paths for Students
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Students can access their learning path in the learning path tab. Here, they can access recommended lecture units and participate in exercises.
-Recommendations (visualized on the left) are generated via an intelligent agent that accounts for multiple metrics, e.g. prior performance, confidence, relations, and due dates, to support students in their selection of learning resources.
-Students can use the up and down buttons to navigate to the previous or next recommendation respectively. Hovering over a node in the list will display more information about the learning resource.
-
-|students-learning-path-participation|
-
-Students can access their learning path graph via the eye icon on the top left. The graph displays all competencies, lecture units, exercises, and their relations. Each competency consists of a start node, visualized by the competency rings displaying progress, confidence, and overall mastery, and an end node represented by a checkered flag. Edges link learning resources to a competency via the respective start and end nodes. If the resource is still pending, it displays as a play symbol. Upon completion of the task, it appears as a checkmark.
-Users can read the graph from top to bottom, starting with the competencies that have no prerequisites, continuing downwards toward competencies that build upon prior knowledge. Students can zoom, pan, and drag the graph to navigate. For better orientation, the top right corner contains a mini-map.
-On the bottom right of the graph, users can view a legend describing the different types of nodes.
-Hovering over any node, e.g. exercise or competency, opens a popover containing essential information about the item, e.g. the type of exercise and title, or for competencies, the details, including the description.
-
-|students-learning-path-graph|
-
-Learning Paths for Instructors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Instructors can enable learning paths for their courses either by editing the course or on the dedicated learning path management page. This will generate individualized learning paths for all course participants.
-
-Once the feature is enabled, instructors get access to each student's learning path. Instructors can search for students by login or name and view their respective learning path graph.
+Students can track their progress in :ref:`competencies_student` and view the next recommended content in their :ref:`learning_paths_student`.
 
-|instructors-learning-path-management|
+Instructors have multiple ways to add competencies to their course: They can :ref:`create new competencies<create_competencies>`, :ref:`import existing ones <import_competencies>` or :ref:`generate competencies <generate_competencies>` using the integrated LLM subsystem of Artemis.
+They can also then link exercises and lecture units to competencies and define competency relations. These relations determine the order in which competencies are presented in the students' learning paths.
 
+Administrators :ref:`manage the standardized competency catalog <standardized_competency_catalog>`, an instance-wide catalog from which instructors can import competencies into their course.
 
+.. toctree::
 
-.. |students-learning-goals-statistics| image:: adaptive-learning/students-learning-goals-statistics.png
-    :width: 1000
-.. |students-learning-goals-statistics-detail| image:: adaptive-learning/students-learning-goals-statistics-detail.png
-    :width: 1000
-.. |instructors-learning-goals-manage| image:: adaptive-learning/instructors-learning-goals-manage.png
-    :width: 1000
-.. |instructors-learning-goal-edit| image:: adaptive-learning/instructors-learning-goal-edit.png
-    :width: 1000
-.. |instructors-learning-goals-link| image:: adaptive-learning/instructors-learning-goals-link.png
-    :width: 600
-.. |students-learning-path-participation| image:: adaptive-learning/students-learning-path-participation.png
-    :width: 1000
-.. |students-learning-path-graph| image:: adaptive-learning/students-learning-path-graph.png
-    :width: 1000
-.. |instructors-learning-path-management| image:: adaptive-learning/instructors-learning-path-management.png
-    :width: 1000
+   adaptive-learning/adaptive-learning-student
+   adaptive-learning/adaptive-learning-instructor
+   adaptive-learning/adaptive-learning-admin

docs/user/adaptive-learning/adaptive-learning-admin.rst

@@ -0,0 +1,68 @@
+Manage Standardized Competencies (Administrator)
+==================================================
+
+.. contents:: Content of this document
+    :local:
+    :depth: 2
+
+.. _standardized_competency_catalog:
+
+Standardized Competencies
+-------------------------
+
+| The **Standardized Competency Catalog** is a catalog of competencies that is accessible to all instructors in an Artemis instance.
+  Instructors may view this catalog and import competencies from it into their course.
+| The competencies consist of a title, description and taxonomy. Instead of being tied to specific courses, competencies are organized under knowledge areas.
+| Knowledge areas may also contain other knowledge areas, enabling a hierarchical structure (e.g., Artificial Intelligence -> Machine Learning).
+
+Manage Standardized Competencies
+--------------------------------
+
+.. note::
+    This is the documentation for administrators. If you are looking for the documentation on importing standardized competencies as an instructor, go :ref:`here<instructor_import_standardized_competencies>`.
+
+.. note::
+
+    To use this feature, the *standardized competency feature toggle* needs to be enabled.
+    To enable it go to Server Administration -> Feature Toggles and make sure the box next to *StandardizedCompetencies* is checked
+
+.. raw:: html
+
+    <iframe src="https://live.rbg.tum.de/w/artemisintro/46942?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="350">
+        Watch this video on TUM-Live.
+    </iframe>
+
+| Administrators can manage the standardized competency catalog of their Artemis instance
+  in the *Standardized Competency Management* view.
+
+| They can filter the displayed content by competency title and knowledge area.
+  Clicking on a knowledge area expands it and clicking on the eye icon shows the knowledge area details on the right.
+| From this details view they can edit or delete the knowledge area, or create new knowledge areas and competencies under it.
+  Likewise, clicking on a standardized competency opens its details, allowing administrators to edit or delete it.
+| Finally, administrators can also import a standardized competency catalog from a JSON file,
+  or export the standardized competency catalog of their Artemis instance into a JSON file.
+
+
+|admin-manage-standardized-competencies|
+
+Import a Standardized Competency Catalog
+----------------------------------------
+
+.. note::
+
+    To obtain a file containing a standardized competency catalog, you can contact the Artemis developer team.
+
+
+| When importing, administrators first view a collapsible example of the expected file structure.
+  They can then select a file containing standardized competencies from their local system.
+| Artemis displays a preview of the knowledge areas and competencies that will be imported
+  and administrators can view the details for each competency by clicking on it.
+| After clicking on import, the complete catalog will be imported into the Artemis instance.
+
+|admin-import-standardized-competencies|
+
+.. |admin-import-standardized-competencies| image:: admin/import-standardized-competency-catalog.png
+    :width: 1000
+
+.. |admin-manage-standardized-competencies| image:: admin/standardized-competency-management.png
+    :width: 1000

docs/user/adaptive-learning/adaptive-learning-instructor.rst

@@ -0,0 +1,150 @@
+Manage Adaptive Learning (Instructor)
+=======================================
+
+.. contents:: Content of this document
+    :local:
+    :depth: 2
+
+.. note::
+
+    When introducing adaptive learning into a course for the first time, you can quickly create a competency model by:
+
+    - :ref:`Generating competencies using an integrated LLM<generate_competencies>`
+    - :ref:`Importing standardized competencies into your course<instructor_import_standardized_competencies>`
+
+    (Given that these features are enabled on your Artemis instance)
+
+Competencies
+------------
+A competency is an overarching learning objective that ties together various lectures and exercises. It has a title, description and a `taxonomy <https://en.wikipedia.org/wiki/Bloom%27s_taxonomy>`_.
+By completing lectures and exercises, students gain mastery of a competency (see also :ref:`Competencies for Students<competencies_student>`).
+
+A prerequisite is a competency that students are expected to have already mastered before the course. Instructors select competencies from previous courses they taught as a prerequisite, or create new ones.
+
+Manage Competencies
+^^^^^^^^^^^^^^^^^^^^
+Instructors can manage competencies and prerequisites of a course in the *Competency Management* view. Here they can:
+
+* View all competencies and prerequisites of their course
+* Create, edit or delete competencies and prerequisites
+* Manage relations between competencies (which are necessary to build learning paths)
+* :ref:`import_competencies` from other courses or the :ref:`standardized competency catalog<standardized_competency_catalog>`
+* :ref:`generate_competencies` using LLMs
+
+|instructor-competency-management|
+
+.. _create_competencies:
+
+Create/Edit Competencies
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+| An instructor can create or edit competencies using the following form.
+  Besides a title and description, they can set a `taxonomy <https://en.wikipedia.org/wiki/Bloom%27s_taxonomy>`_.
+| The mastery threshold describes the minimum average score required for a student to reach 100% confidence in this competency.
+  The current average score of all linked exercises shown on this page can be used as a basis for defining a reasonable threshold value.
+| Instructors can link competencies to lecture units on this page by first choosing a lecture and then selecting desired lecture units.
+
+|instructor-competency-edit|
+
+Alternatively, instructors can also link competencies to an exercise or lecture unit on the respective management page using the selection box shown below.
+
+|instructor-competency-link|
+
+.. _import_competencies:
+
+Import Competencies
+^^^^^^^^^^^^^^^^^^^
+
+Instructors have three ways to import competencies: Import all competencies of another course, import from other courses or import standardized competencies.
+
+**1. Import all Competencies of another Course**
+
+| This option opens a modal in which instructors can select one of their previous courses, importing all competencies (and relations) into the current course.
+| The purpose of this feature is to directly import the complete competency model of another course, e.g. when holding courses repeatedly.
+
+|instructor-import-all-competencies|
+
+**2. Import from other Courses**
+
+| When importing from other courses, instructors can view a list of competencies from all courses they have access to.
+  They can sort the list based on all fields except for competency description.
+  They can also filter the list through the *Competency Search* at the top of the page, which can be expanded for advanced search options.
+| All selected competencies are displayed in the *Selected Competencies* table and can be de-selected again by clicking on the trash bin icon.
+  Finally, instructors can select if they also want to import the relations between the imported competencies.
+
+|instructor-import-competencies|
+
+.. _instructor_import_standardized_competencies:
+
+**3. Import Standardized Competencies**
+
+.. note::
+
+    To use this feature, the *standardized competency feature toggle* needs to be enabled.
+    If you have no access to the feature, contact your instance administrators.
+
+| When importing standardized competencies, instructors can view the complete :ref:`standardized competency catalog<standardized_competency_catalog>` of their Artemis instance.
+  They can filter the displayed competencies by title and knowledge area.
+| Clicking on the name of a competency opens its details on the right side and clicking on the checkbox next to the name selects it for import.
+  Again, selected competencies are displayed in a table and can be de-selected again by clicking on the trash bin icon.
+
+|instructor-import-standardized-competencies|
+
+.. _generate_competencies:
+
+Generate Competencies
+^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    To use this feature, Iris needs to be enabled for your Artemis instance and *Competency Generation* needs to be enabled in the Iris global settings **as well as the Iris settings of your course** (see image below).
+    If you cannot enable *Competency Generation* in your Iris course settings, contact your instance administrators.
+
+|competency-generation-settings|
+
+.. raw:: html
+
+    <iframe src="https://live.rbg.tum.de/w/artemisintro/46941?video_only=1&t=0" allowfullscreen="1" frameborder="0" width="600" height="350">
+        Watch this video on TUM-Live.
+    </iframe>
+
+| Instructors can use the integrated LLM subsystem of Artemis, to generate competencies for their course.
+| Based on a course description, the LLM generates around 10 recommendations for possible competencies (the amount may vary depending on the description provided).
+
+|instructor-generate-competencies|
+
+| Instructors can view the details (title, description and taxonomy) of each recommendation by expanding it.
+  They can then edit these details or delete the recommendation if it is unfit.
+| After saving, the recommendations are saved as actual competencies into the course of the instructor.
+
+|instructor-competency-recommendation|
+
+Learning Paths
+--------------
+
+Instructors can enable learning paths for their courses either by editing the course or on the dedicated learning path management page. This will generate individualized learning paths for all course participants.
+
+Once the feature is enabled, instructors get access to each student's learning path. Instructors can search for students by login or name and view their respective learning path graph.
+
+|instructors-learning-path-management|
+
+.. |instructor-competency-management| image:: instructor/manage-competencies.png
+    :width: 1000
+.. |instructor-import-all-competencies| image:: instructor/import-all-competencies.png
+    :width: 600
+.. |instructor-import-competencies| image:: instructor/import-course-competencies.png
+    :width: 1000
+.. |instructor-import-standardized-competencies| image:: instructor/import-standardized-competencies.png
+    :width: 1000
+.. |instructor-competency-edit| image:: instructor/competency-edit.png
+    :width: 1000
+.. |instructor-competency-link| image:: instructor/competency-link.png
+    :width: 600
+.. |instructor-generate-competencies| image:: instructor/generate-competencies.png
+    :width: 1000
+.. |instructor-competency-recommendation| image:: instructor/competency-recommendation.png
+    :width: 1000
+.. |instructors-learning-path-management| image:: instructor/learning-path-management.png
+    :width: 1000
+.. |competency-generation-settings| image:: competency-generation-settings.png
+    :width: 600