docs: aspects full documentation (#228)

This commit contains all the Aspects of documentation for the different roles and a modification of the technical documentation order. It also represents the links already set up for the help tabs in Aspects.
openedx · Jun 25, 2024 · 0bdf349 · 0bdf349
1 parent 20eefbf
commit 0bdf349
Show file tree

Hide file tree

Showing 119 changed files with 620 additions and 14 deletions.
diff --git a/docs/_static/activity_logs.png b/docs/_static/activity_logs.png
diff --git a/docs/_static/add_alert.png b/docs/_static/add_alert.png
diff --git a/docs/_static/add_cross_filter.png b/docs/_static/add_cross_filter.png
diff --git a/docs/_static/apply_button.png b/docs/_static/apply_button.png
diff --git a/docs/_static/apply_button_new.png b/docs/_static/apply_button_new.png
diff --git a/docs/_static/at_risk_dashboard.png b/docs/_static/at_risk_dashboard.png
diff --git a/docs/_static/atrisk_engagement.png b/docs/_static/atrisk_engagement.png
diff --git a/docs/_static/atrisk_performance.png b/docs/_static/atrisk_performance.png
diff --git a/docs/_static/autorefresh_option.png b/docs/_static/autorefresh_option.png
diff --git a/docs/_static/clear_button.png b/docs/_static/clear_button.png
diff --git a/docs/_static/course_dashboard_new.png b/docs/_static/course_dashboard_new.png
diff --git a/docs/_static/course_filters.png b/docs/_static/course_filters.png
diff --git a/docs/_static/database_connect.png b/docs/_static/database_connect.png
diff --git a/docs/_static/database_settings.png b/docs/_static/database_settings.png
diff --git a/docs/_static/database_type.png b/docs/_static/database_type.png
diff --git a/docs/_static/download_button.png b/docs/_static/download_button.png
diff --git a/docs/_static/edit_role.png b/docs/_static/edit_role.png
diff --git a/docs/_static/engagement_page.png b/docs/_static/engagement_page.png
diff --git a/docs/_static/engagement_problems_new.png b/docs/_static/engagement_problems_new.png
diff --git a/docs/_static/engagement_videos.png b/docs/_static/engagement_videos.png
diff --git a/docs/_static/enrollment_metrics_new.png b/docs/_static/enrollment_metrics_new.png
diff --git a/docs/_static/expand_filters.png b/docs/_static/expand_filters.png
diff --git a/docs/_static/export_options.png b/docs/_static/export_options.png
diff --git a/docs/_static/filter_icon.png b/docs/_static/filter_icon.png
diff --git a/docs/_static/filters_panel.png b/docs/_static/filters_panel.png
diff --git a/docs/_static/hover_filters.png b/docs/_static/hover_filters.png
diff --git a/docs/_static/individual_dashboard.png b/docs/_static/individual_dashboard.png
diff --git a/docs/_static/moreoptions_button.png b/docs/_static/moreoptions_button.png
diff --git a/docs/_static/new_record.png b/docs/_static/new_record.png
diff --git a/docs/_static/operator_dashboard.png b/docs/_static/operator_dashboard.png
diff --git a/docs/_static/performance_metrics.png b/docs/_static/performance_metrics.png
diff --git a/docs/_static/refresh_box.png b/docs/_static/refresh_box.png
diff --git a/docs/_static/refresh_button.png b/docs/_static/refresh_button.png
diff --git a/docs/_static/remove_cross_filter.png b/docs/_static/remove_cross_filter.png
diff --git a/docs/_static/reports_tab.png b/docs/_static/reports_tab.png
diff --git a/docs/_static/security.png b/docs/_static/security.png
diff --git a/docs/_static/superset_link.png b/docs/_static/superset_link.png
diff --git a/docs/_static/superset_overview.png b/docs/_static/superset_overview.png
diff --git a/docs/_static/superset_permissions.png b/docs/_static/superset_permissions.png
diff --git a/docs/_static/superset_singin.png b/docs/_static/superset_singin.png
diff --git a/docs/_static/time_filters.png b/docs/_static/time_filters.png
diff --git a/docs/_static/viewall_button.png b/docs/_static/viewall_button.png
diff --git a/docs/administator/concepts/index.rst b/docs/administator/concepts/index.rst
@@ -0,0 +1,10 @@
+Concepts
+########
+
+
+.. toctree::
+   :maxdepth: 2
+
+   role_description
+   permissions
+
diff --git a/docs/administator/concepts/permissions.rst b/docs/administator/concepts/permissions.rst
@@ -0,0 +1,12 @@
+Permissions
+###########
+
+The permissions work by consulting the LMS APIs, the permission used is “course_staff.” Once granted, users are able to enter the LMS and assume the role of instructor, with which they can visit the assigned dashboard to its language code.
+
+Please refer to the `Superset official documentation <https://superset.apache.org/docs/security/>`_ for more information. 
+
+Manage Roles
+************
+New roles and assignment rules can be created for them, and their permissions must also be configured. Those can be added programmatically, allowing you better control over their deployment and synchronization, or manually. This is not recommended, as the state of the installation can not be readily determined from the source code and can cause weird behavior.
+
+To learn more about this topic, review the `technical documentation <superset_roles>`_.
diff --git a/docs/administator/concepts/role_description.rst b/docs/administator/concepts/role_description.rst
@@ -0,0 +1,27 @@
+Role Description
+################
+
+A Site Operator, also referred to as an Administrator, in Aspects holds the highest level of permissions within the platform. They possess complete control over user access, data, and configurations and are considered Super Users.
+
+Here's a breakdown of their key responsibilities:
+
+- **User Management:**
+	- Creating, editing, and deleting user accounts.
+	- Assigning roles and permissions to users and determining their access level to data sources, dashboards, and functionalities.
+
+- **Data Source Management:**
+	- Adding, configuring, and editing data sources that provide information for visualizations.
+	- Ensuring secure connections and proper data retrieval from various sources.
+
+- **Security Administration:**
+	- Maintaining the overall security of Superset by configuring authentication methods and access controls.
+	- Monitoring user activity and addressing any security concerns.
+
+- **System Administration:**
+	- Configuring global settings for Superset, such as date/time formats and display options.
+	- Managing system resources and ensuring smooth operation of the platform.
+
+- **Content Management:**
+	- While not exclusive to Site Operators, they have full access to create, edit, and share dashboards and reports within Superset.
+
+Site Operators act as Superset's system administrators, granting access, ensuring data security, and overseeing the platform's overall functionality.
diff --git a/docs/administator/how_to/activity_logs.rst b/docs/administator/how_to/activity_logs.rst
@@ -0,0 +1,18 @@
+How to Explore the Activity Logs of Superset Users
+##################################################
+
+1. Go to your platform's Superset site. Remember that you can use the link in the LMS Instructor Tab. Visit `How to Access Aspects <access_aspects>`_ to refresh your knowledge of this process.
+
+2. Log in to Superset with your administrator credentials.
+
+3. Locate the **Security** section of the **Settings menu**.
+
+.. image:: /_static/security.png
+
+4. Access the **Action Log** option.
+
+5. You can see and filter different users' recent activity on the platform. 
+
+6. Click on the **Show Record** icon to see the details of each event.
+
+.. image:: /_static/activity_logs.png
diff --git a/docs/administator/how_to/alerts_and_reports.rst b/docs/administator/how_to/alerts_and_reports.rst
@@ -0,0 +1,20 @@
+How to Manage Alerts and Reports
+################################
+
+Superset provides robust functionality for managing alerts and reports. Users can set up automated notifications based on data thresholds and schedule the delivery of reports to designated recipients. This feature enhances data-driven decision-making by ensuring stakeholders receive timely insights and updates.
+
+1. Go to your platform's Superset site. Remember that you can use the link in the LMS Instructor Tab. Visit `How to Access Aspects <access_aspects>`_ to refresh your knowledge of this process.
+
+2. Log in to Superset with your administrator credentials.
+
+3. Locate the **Manage** section of the **Settings menu**.
+
+4. Access the **Alerts and Reports** option to see the list.
+
+5. Click the **+ Alert** button to add a new alert or the edit icon to edit an existing one.
+
+.. image:: /_static/add_alert.png
+
+6. Add a notification method to have the alert be sent by email and configure the email recipients.
+
+7. Finally, hit **Add** to have this automation in place.
diff --git a/docs/administator/how_to/create_new_role.rst b/docs/administator/how_to/create_new_role.rst
@@ -0,0 +1,20 @@
+How to Create a New Role
+########################
+
+1. Go to your platform's Superset site. Remember that you can use the link in the LMS Instructor Tab. Visit `How to Access Aspects <access_aspects>`_ to refresh your knowledge of this process.
+
+2. Log in to Superset with your administrator credentials.
+
+3. Locate the **Security** section of the **Settings menu**.
+
+.. image:: /_static/security.png
+
+4. Access the **List Roles** option to see the list of roles.
+
+5. Click the **Add New Record** button to add a new role or the edit icon to edit an existing one.
+
+.. image:: /_static/new_record.png
+
+6. Fill in the required information and click **Save**.
+
+.. image:: /_static/edit_role.png
diff --git a/docs/administator/how_to/database_connections.rst b/docs/administator/how_to/database_connections.rst
@@ -0,0 +1,26 @@
+How to Manage Additional Database Connections
+#############################################
+
+Superset allows users to efficiently manage database connections by providing a user-friendly interface for configuring, testing, and maintaining connections to various data sources. This feature streamlines the process of connecting to databases, making it easier for users to access and analyze their data within the platform and potentially across other platforms or data sources.
+
+1. Go to your platform's Superset site. Remember that you can use the link in the LMS Instructor Tab. Visit `How to Access Aspects <access_aspects>`_ to refresh your knowledge of this process.
+
+2. Log in to Superset with your administrator credentials.
+
+3. Locate the **Data** section of the **Settings menu**.
+
+4. Access the **Database Connections** option to see the list.
+
+5. Click the **+ Database** button to add a new database connection or the edit icon to edit an existing one.
+
+6. Select the type of database.
+
+.. image:: /_static/database_type.png
+
+7. Provide the required information and click **Connect**.
+
+.. image:: /_static/database_connect.png
+
+8. Adjust the settings for the new connection and click **Finish**.
+
+.. image:: /_static/database_settings.png
diff --git a/docs/administator/how_to/export_tabular_data.rst b/docs/administator/how_to/export_tabular_data.rst
@@ -0,0 +1,18 @@
+How to Export Tabular Data from a Chart or Table in an Aspects Dashboard
+#########################################################################
+
+You can download data from Superset in different formats, but probably the most relevant for any Site Operator is how to export tabular data from a chart or table. 
+
+1. Click the three-dot icon in the upper corner of any chart or table in an Aspects dashboard.
+
+.. image:: /_static/moreoptions_button.png
+
+2. Select **Download**.
+
+3. Select **Export to CSV** to export the table as a CSV file or **Export to Excel** to export the table as an Excel file.
+
+.. image:: /_static/export_options.png
+
+4. The exported file will appear in your **Downloads** folder.
+
+.. seealso:: To learn how to export information as a PDF or as an image, visit `How to Downloading Reports in Superset Dashboards <download_reports>`_.
diff --git a/docs/administator/how_to/index.rst b/docs/administator/how_to/index.rst
@@ -0,0 +1,13 @@
+How-to's 
+#########
+
+
+.. toctree::
+   :maxdepth: 2
+
+   create_new_role
+   activity_logs
+   database_connections
+   alerts_and_reports
+   view_data
+   export_tabular_data
diff --git a/docs/administator/how_to/view_data.rst b/docs/administator/how_to/view_data.rst
@@ -0,0 +1,13 @@
+How to View Data About an Open edX Instance
+###########################################
+
+1. Once you access Superset with administrator credentials, go to the **Operator Dashboard**.
+
+.. image:: /_static/operator_dashboard.png
+
+2. Click the **View All button** if the **Operator Dashboard** doesn’t appear in the Dashboards Section.
+
+.. image:: /_static/viewall_button.png
+
+3. Find and click the link to the Operator Dashboard from the list of all available dashboards.
+
diff --git a/docs/administator/index.rst b/docs/administator/index.rst
@@ -0,0 +1,10 @@
+Administrator and Site Operator User Documentation
+##################################################
+
+.. toctree::
+   :maxdepth: 2
+
+   Concepts <concepts/index>
+   How-To's <how_to/index>
+   Reference <reference/index>
+
diff --git a/docs/administator/reference/index.rst b/docs/administator/reference/index.rst
@@ -0,0 +1,26 @@
+Reference 
+#########
+
+Advanced Configuration Options in ASPECTS
+*****************************************
+
+By modifying the configuration files, you can alter the ASPECTs platform differently.
+
+You can configure whether to sync personal information such as user profiles and IDs.
+
+Sentry can be configured in all three services (LMS, Superset, and Ralph)
+
+Extra requirements can be added to the Superset.
+
+Extra Jinja filters can be added, allowing permission checks for other roles and filtering information based on information from other services.
+You can change the default language, although the current ASPECTS version only focuses on English language support.
+
+Visit the official superset documentation to find out more: `<https://superset.apache.org/docs/installation/configuring-superset>`_.
+
+Branding
+********
+Branding is not currently configurable for Aspects. This means that the superset logo will be visible on all the consoles.  However, there is ongoing work to make it configurable to some extent.  `<https://github.com/openedx/tutor-contrib-aspects/issues/222>`_.
+
+Configure Aspects for Production
+********************************
+To have more information about the diferent posibilities that you have with Aspects, please visit the `Production Configuration Documents <production_configuration>`_
diff --git a/docs/course_team/concepts/filters.rst b/docs/course_team/concepts/filters.rst
@@ -0,0 +1,20 @@
+Filters
+#######
+
+Superset dashboards allow you to filter the data displayed in the charts and graphs, which can help you focus on specific data sets or trends. 
+
+Types of Filters
+****************
+
+There are three main types of filters in Superset dashboards:
+
+- **Course Filters:** These filters allow you to specify which courses you want to see data for. For example, in the following image, the course filters include Organization, Course Name, and Course Run, which are currently set to specific examples.  
+
+.. image:: /_static/course_filters.png
+
+
+- **Time Filters:** These filters allow you to specify the period you want to see data for. The "Date" filter in the image is currently set to "No filter." There is also a "Time Grain" filter that you can use to change the time interval shown in the graph (e.g., day, week, month).
+
+.. image:: /_static/time_filters.png
+
+- **Individual Learner Filters:** These filters on the Individual Learner Dashboard allow you to filter the enrollment, engagement, and performance information for a single learner in your course at a time. By default, no filter is applied to the Name, Username, or Email filter.  
diff --git a/docs/course_team/concepts/index.rst b/docs/course_team/concepts/index.rst
@@ -0,0 +1,11 @@
+Concepts
+########
+
+
+.. toctree::
+   :maxdepth: 2
+
+   role_and_permissions
+   superset_overview
+   filters
+
diff --git a/docs/course_team/concepts/role_and_permissions.rst b/docs/course_team/concepts/role_and_permissions.rst
@@ -0,0 +1,17 @@
+Role Description and Permissions
+################################
+
+As a course delivery team member, you may want to monitor the learners' performance to determine how to help them and evaluate the general course output, and Aspects can help you with that.
+
+What can you do in Aspects?
+===========================
+With this role, the course team members have access to the Course Dashboard, the At-Risk Learner Dashboard, and the Individual Learner Dashboard, depending on the type of dashboard created by the platform administrator. 
+You can generally navigate through the dashboards from the Instructor tab in the LMS and access Superset, the open-source data exploration and visualization tool used for Aspects, to modify the reports using the filters available. 
+You can also download information as a PDF or image to use or communicate it as you want.
+
+What you cannot do in Aspects?
+==============================
+The principal functions that are not available for the users with course delivery team roles are:
+- Create new dashboards.
+- Permit new course delivery team members. However, course admins can add course staff to their courses, who will then have access to Aspects.
+- Modify the general settings of the tool.
diff --git a/docs/course_team/concepts/superset_overview.rst b/docs/course_team/concepts/superset_overview.rst
@@ -0,0 +1,39 @@
+Superset Overview
+#################
+
+Apache Superset is an open-source platform that is the primary data visualization and exploration tool for Aspects. But here, more than explaining Superset's benefits, let us discuss how to navigate it. 
+
+If you want to learn more about Superset, please visit the Concept section, or if you want to learn more about why we chose this tool for the project, please visit the Decision section in the Technical Documentation.
+
+The Superset Home Page provides an overview of the dashboards available and quick access to different sections for managing your data visualizations.
+
+.. image:: /_static/superset_overview.png
+
+
+On the navigation bar at the top of the home page, you will find a series of buttons to access the tool's different options and configurations. Depending on your permissions, you might or might not have certain buttons or more options in certain menus.
+
+The buttons are:
+
+- **Dashboards:** This button leads you to a section where you can create and manage dashboards.
+
+- **Charts:** This button leads you to a section where you can create and manage charts.
+
+- **Datasets:** This button leads you to a section where you can manage datasets for your visualizations.
+
+- **SQL:** This button leads to a SQL editor where you can write and execute SQL queries.
+
+- **+:** This button allows you to create new dashboards or charts and add new SQL queries and data sets.
+
+- **Settings:** This button leads to a section where you can manage user settings and configure Superset.
+
+Below the navigation bar, you will find different sections where the dashboards and charts are organized to improve your platform navigation experience. Those sections are:
+
+- **Recents:** Here, you will find the latest dashboards and charts viewed or edited by you.
+
+- **Dashboards:** In this section, you will find all the dashboards published by your organization.
+
+- **Charts:** Here, you can access all the charts created by your organization for each course, like Video Engagement or Problem Attempts.
+
+- **Saved Queries:** This section will contain all the SQL queries you create, add, or edit on your organization’s Aspects.
+
+.. note:: This information is also relevant to users with administrator roles. 
diff --git a/docs/course_team/how-tos/access_aspects.rst b/docs/course_team/how-tos/access_aspects.rst
@@ -0,0 +1,27 @@
+How to Access Aspects as a Course Delivery Team Member
+######################################################
+
+Once the Administrator has assigned you the course delivery team role and permitted you to do so, you will have access to the reports from the LMS by following these simple steps.
+
+1. In the LMS, go to the **Instructor** Tab.
+
+2. Select the **Reports** tab.
+
+.. image:: /_static/reports_tab.png
+
+There you will see the three principal dashboards of Aspects: the `Course Dashboard <course_overview_dashboard>`_, the `Individual Learner Dashboard <individual_learner_dashboard>`_, and the `At Risk Learner Dashboard <learner_groups_dashboard>`_. From these dashboards, you will see the course and learner information that Aspects has collected.
+
+
+3. Above the dashboards, you will find a link to access the dashboards from Superset, modify the filters, and download the reports.
+
+.. image:: /_static/superset_link.png
+
+4. Click the **Allow** button.
+
+.. image:: /_static/superset_permissions.png
+
+5. Click **Sign in with Open edX SSO** button.
+
+.. image:: /_static/superset_singin.png
+
+.. note:: If the link to Superset does not appear, your site operator has elected to disable this link from being shown on your Open edX instance.
diff --git a/docs/course_team/how-tos/apply_filters.rst b/docs/course_team/how-tos/apply_filters.rst
@@ -0,0 +1,30 @@
+How to Apply Filters in a Superset Dashboard
+############################################
+
+The filters are one of the most important features that Aspects brings to edit the type of information that you can access. Let's see how to apply them in any of the dashboards.
+
+1. Once you can access Superset, select the dashboard you want to work on.
+
+2. At the left panel, you will find all the filter categories that apply to the information dashboard. Click on the dropdown menu of the filters to see the option lists.
+
+.. image:: /_static/filters_panel.png
+
+3. To modify a filter, select the desired option from the list. You can also use the search bar to find specific courses or dates.
+
+4. Once you have selected your filters, click the **Apply Filters** button to update the dashboard.
+
+.. image:: /_static/apply_button_new.png
+
+5. Hover over the filter icon to view what filters have been applied to the chart or table.
+
+.. image:: /_static/hover_filters.png
+
+Clearing Filters
+****************
+The dashboard also has a **Clear All** button that you can use to remove all of the filters and reset the dashboard to its default state.
+
+.. image:: /_static/clear_button.png
+
+.. note:: You can apply multiple filters simultaneously. For example, you could filter the data to show only courses from a specific organization for a particular date range.
+
+.. note:: The available filters will depend on the specific dashboard you are viewing.