Improve instructor's doc

doc/src/container-admins.md

@@ -266,6 +266,7 @@ Note that the value for `c.LTI13Authenticator.client_id` has to be a list of str
 Don't abuse `30_lms.py` for other configuration purposes than the described LTI configuration.
 This may lead to unexpected behavior.
 
+(lit-lms)=
 #### LMS
 
 For your LMS you need the following configuration information (field names are taken from Moodle here and may be slightly different in other LMS):

doc/src/instructors.md

@@ -28,46 +28,55 @@ If you want to provide data to your hub users or if hub user shall have access t
 
 ## Nbgrader
 
+### Course management
+
+```{note}
+Here we use Moodle terminology. Other LMS may denote things differently.
+```
+
+In your LMS you may either configure an 'external tool' activity yourself (see [LMS configuration for container admins](#lti-lms)) or your LMS admin provides preconfigured external tools. In case of self-configuration you have to provide the client ID generated by the LMS for the external tool to your container admin. Alternatively, if your LMS allows for custome client IDs, you may get a client ID from your container admin. In both cases connection between LMS and Jupyter only works if both sides know the common client ID.
+
+Each Jupyter activity in your LMS generates a separate nbgrader course in Jupyter. The nbgrader course's title gets autogenerated from the LMS course title and the activity title.
+
+```{important}
+As soon as you have created a new Jupyter activity in your LMS (and client IDs are known to both sides) log in to Jupyter via this activity. Else stundent's log in won't work. You have to be the first who logs in!
+```
+
+```{note}
+After creating a new Jupyter activity, your first log in to Jupyter via this activity will take up tp 60 seconds due to lots of background work for creating corresponding nbgrader course and user management. Even if you see JupyterLab's GUI wait another 10 second and ignore cumbersome messages (click 'Dismiss').s. Subsequent logins and your student's login will be much faster.
+```
+
+If students log in to Jupyter via the LMS activity they automatically get enroled to the corresponding nbgrader course. Once enroled, they have access to all their nbgrader courses. Which activity is chosen for entering Jupyter then does not matter anymore.
+
 ### Basic usage
 
 To create and manage nbgrader assignments in your JupyterLab session click 'Nbgrader', 'Course List'.
 In the list, click your course.
 A new JupyterLab session opens.
-This session belongs to a separate user account created for the course.
+**This session belongs to a separate user account created for the course.** All instructors of the corresponding LMS activity have access to this account.
 
 In the course's Lab session click 'Nbgrader', 'Formgrader'.
 Usage of the formgrader GUI is described in [nbgrader's documentation](https://nbgrader.readthedocs.io/en/stable/user_guide/creating_and_grading_assignments.html).
 
-```{important}
-If you create a new course in your LMS you have to visit the hub via that course before any student is able to use the course.
-On first visit modified course structure is synced between LMS and JupyterHub.
-```
-
-```{hint}
-After creating a new LMS course the first login to the hub from this course takes several seconds.
-Even if you see the JupyterLab GUI wait another 5 seconds and ignore cumbersome messages appearing on screen (click 'Dismiss').
-The hub is restarting in the background, which takes a while.
-```
-
 ```{note}
 When collecting submissions with the formgrader, nbgrader will complain about possible cheating attempts in the log output due to unexpected file ownerships. This warning can be savely ignored as long as no student tries cheating ;-) The warning is caused by Ananke's management of user accounts. Developers plan to tackle this problem in a future release.
 ```
 
 ### Feedback configuration
 
-Nbgrader provides two configuration options for feedback generation. In the course's Lab open a terminal and run `nano .jupyter/nbgrader_config.py`. A console based text editor will open showing a few lines of Python code. Do not change anything here except for (un)commenting following two lines:
-* If `'nbgrader.preprocessors.ClearHiddenTests',` is active (not commented out), then students won't see the code of hidden tests in their feedback files. Else you will disclose your hidden tests. Note that this option does not (!) remove output of hidden tests.
-* If `'nbgrader.preprocessors.Execute'` is active (not commented out), then the students' notebooks will be reexecuted. If you have removed code of hidden tests with above option, then reexecution will remove output of hidden tests, too (including tracebacks). Whether this is a good idea depends on your test and feedback design, because reexecution will remove any outputs (feedback!) from hidden tests, too.
+Nbgrader provides two configuration options for feedback generation. In the course's Lab open a terminal and run `nano ~/.jupyter/nbgrader_config.py`. A console based text editor will open showing a few lines of Python code. Do not change anything here except for (un)commenting following two lines:
+* If `'nbgrader.preprocessors.ClearHiddenTests',` is active (not commented out), then students won't see the code of hidden tests in their feedback files. Else you will disclose your hidden tests. Note that this option does not (!) remove output of hidden tests. Default for new courses is 'active'.
+* If `'nbgrader.preprocessors.Execute'` is active (not commented out), then the students' notebooks will be reexecuted. If you have removed code of hidden tests with above option, then reexecution will remove output of hidden tests, too (including tracebacks). Whether this is a good idea depends on your test and feedback design, because reexecution will remove any outputs (feedback!) from hidden tests, too. Default for new courses is 'inactive'.
 
-Close the editor with Ctrl-C, then Y, then return. Close the terminal by typing `logout`.
+Close the editor with `Ctrl-C`, then `Y`, then `return`. Close the terminal by typing `logout`.
 
 ```{note}
 For unknown reasons nbgrader shows a warning `Config option 'display_data_priority' not recognized by 'ClearHiddenTests'` while generating feedback. This warning can be savely ignored.
 ```
 
 ### Further configuration
 
-To use custom delimiters for your sample solution add following lines to the formgrader user's `.jupyter/nbgrader_config.py` (cf. above):
+To use custom delimiters for your sample solution add following lines to the formgrader user's `~/.jupyter/nbgrader_config.py` (cf. above):
 ```python
 c.ClearSolutions.begin_solution_delimeter = "BEGIN MY SOLUTION"
 c.ClearSolutions.end_solution_delimeter = "END MY SOLUTION"
@@ -79,14 +88,16 @@ c.ClearSolutions.code_stub = {
     "python": "YOUR_DEFAULT_CODE_FOR_STUDENT_CELLS"
 }
 ```
-to `.jupyter/nbgrader_config.py`.
+to `~/.jupyter/nbgrader_config.py`.
 
-## Kore
+### Kore
 
-The Kore service on the one hand sends nbgrader's grades to the LMS.
+The Kore service shipping with the Ananke Jupyter Distribution on the one hand sends nbgrader's grades to the LMS.
 On the other hand, it provides course management functionality for nbgrader.
 
 Access Kore from your JupyterLab session by clicking the 'Kore' menu item.
-
-Sending grades to the LMS only works for the LMS course you started your Jupyter session from.
-All other functionality works for all your courses.
+* **Sending grades** to the LMS only works for the LMS course you started your Jupyter session from. All other functionality works for all your courses.
+* **Backup** copies the a whole course (including submissions and grades) to your home directory (in your personal JupyterLab).
+* **Import** searches your home directory for backup directories and shows a selection dialog. Imported course files and directories can be renamed in the course's file browser (to rename assignments, for instance).
+* **Reset a course** to remove all students and their data from the course. So you can start with a fresh course without re-creating it.
+* **Delete a course** if you do not need it anymore. All files and the course's user account will be removed. Don't forget to remove corresponding LMS activity, too. Else coming to JupyterHub through this activity will create a new nbgrader course.