improve instructions for new courses

src/instructors/PreperationNewCourses.md

@@ -37,33 +37,70 @@ This means: Only share read-only tokens to repositories which dont contain sensi
 
 In general, the following steps are required for adding a new profile to the cluster:
 
-1. Choose a Jupyter Kernel
-2. Prepare Jupyter Notebooks
-3. Collect Python/Third-Party requirements
-4. Prepare Dockerfile
-5. Submit request for inclusion in profile list
-6. Wait until request is reviewed and the new profile is included in the list
+1. Setup a local test environemnt for preparing your Jupyter Environment
+2. Choose a Jupyter Kernel
+3. Create a new Git repository for Jupyter Notebooks and runtime environemnt
+4. Prepare Jupyter Notebooks
+5. Collect Python/Third-Party requirements
+6. Adapt Dockerfile
+7. Submit request for inclusion in profile list
+8. Wait until request is reviewed and the new profile is included in the list
 
-Hereby, steps 3 to 4 are optional and only required if the course requires a non-standard Jupyter kernel or special Python dependencies.
+Hereby, steps 4.-6. are optional and only required if the course requires a non-standard Jupyter kernel or special Python dependencies.
 
-### 1. Choose a Jupyter Kernel
+### 1. Setup a local test environemnt for preparing your Jupyter Environment
+
+Please follow the instructions from the official Jupyter website: https://jupyter.org/install
+
+For Windows users, we recommend to use the Anaconda Python distribution.
+Linux and macOS users can use Anaconda as well or simply rely on `pip` installed via the systems package manager.
+
+### 2. Choose a Jupyter Kernel
 
 Jupyter supports a variety of different programming languages via different _kernels_.
-The original and most commonly used kernel using the iPython interpreter.
+The original and most commonly used kernel using the [IPython](https://ipython.org/) interpreter.
 However also others exist. An updated lists of kernels can be found at the [Jupyter wiki](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels).
 
 In principle, almost all of the existing kernels can be used on jupyter.rwth-aachen.de by creating custom runtime environments.
-However, this step is not required in all cases. Some courses might just use a standard iPython environment.
+Please consult the documentation for the installation of other kernels and add these instructions to the Dockerfile (step 6).
 
-### 2. Prepare Jupyter Notebooks
+However, in most cases the standard IPython kernel is used and no further steps are necessary.
 
-We recommend to use the [RTWH Software Engineering Services](https://doc.itc.rwth-aachen.de/display/SES/Home) / [GitLab](https://git.rwth-aachen.de) to manage, track, distribute Jupyter Notebooks.
+### 3. Create a new Git repository for Jupyter Notebooks and runtime environemnt
+
+We recommend to use the [RTWH Software Engineering Services](https://doc.itc.rwth-aachen.de/display/SES/Home) / [GitLab](https://git.rwth-aachen.de) to manage, track, distribute Jupyter Notebooks and the definition of the required runtime environment.
 
 This allows for a continous delivery of updates to Jupyter as well as welcomes contributions by Students to the Jupyter notebooks.
 
-**Example Profile:** [https://git.rwth-aachen.de/jupyter/example-profile](https://git.rwth-aachen.de/jupyter/example-profile)
+You can either use an existing Git repository, which might be already existing for a lecture or create a new one by forking our
+[example profile](https://git.rwth-aachen.de/jupyter/example-profile).
+
+Please using the following link to create a new _fork_ of the example profile: [**create fork of example profile**](https://git.rwth-aachen.de/jupyter/example-profile/-/forks/new).
+
+After the fork has been completed, you can clone the fresh repo to your local machine:
+
+```bash
+git clone git@git.rwth-aachen.de:/stvogel/my-new-course.git
+cd my-new-course
+```
+
+### 4. Prepare Jupyter Notebooks
+
+A new profile can include a set of Jupyter notebooks which come along with it.
+These Notebooks are will be synchronized from a Git repository every time a user enters the Jupyter environment.
 
-### 3. Collect Python requirements
+As such, the collection of Notebooks for a course can be expandend during the course of the semester.
+
+To start, please launch Jupyter on your local machine:
+
+```bash
+jupyter lab
+```
+
+A new browser window will open and present you the Jupyter web interface and you should already see the list of existing files in the current Git repository.
+Add new Notebooks and fill them with content to your wishes.
+
+### 5. Collect Python requirements
 
 Depending on the contents of the Jupyter Notebook, additional third-party Python packages might be required.
 Usually these external dependencies are collected in a `requirements.txt` or `environement.yml` file:
@@ -73,11 +110,24 @@ Please have a look at the following links for further information:
 - [Creating Conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually)
 - [PIP Requirements Files](https://pip.pypa.io/en/stable/user_guide/#requirements-files)
 
-### 4. Prepare Dockerfile
+### 6. Adapt Dockerfile
 
-We perpared an example Profile: https://git.rwth-aachen.de/jupyter/example-profile
+Some profiles (e.g. when using special Jupyter Kernels) may require additional modifications to the runtime environemnt beyond the installation of new Python requirements.
+
+To accomodate these the user can modify the included Dockerfile to run arbitrary commands during the preperation of the environemnt.
+Note that these commands are only executed during the Docker build phase.
+
+### 7. Publish Jupyter Notebooks and Dockerfile in Git repository
+
+After completing steps 2.-4., the resulting changes need to be commited to the Git repo and published on a Git hoster (e.g. RWTH GitLab or GitHub):
+
+```bash
+git add .
+git commit -m "first version of new profile"
+git push
+```
 
-### 5. Submit Questionaire for inclusion in profile list
+### 8. Submit questionaire for inclusion in profile list
 
 Please fill out the following template and mail it to [jupyter-admin@lists.rwth-aachen.de](mailto:jupyter-admin@lists.rwth-aachen.de) in order to request the inclusing of your materials as a new profile.