[docs] Addressed reviewer comments.

web/content/docs/devguide/documentation/jupyter-docs/index.md

@@ -17,22 +17,51 @@ parent = "development-workflows"
 
 ## 1. Direct conversion
 
+Consider direct conversion for the following use cases:
+
+- Execution of the notebook is very time-consuming (too long for regular CI tests).
+- The notebook uses Python packages which are not part of the testing environment (see `Tests/Data/requirements*.txt` for available packages).
+- The notebooks needs other custom tools or environment.
+- The shown functionality is not required to be regularly tested.
+
+### Create a new notebook
+
 Create a new notebook file in `web/contents/docs/[some-section]/my-page/my-page.ipynb`. It is important that the notebook filename is the same as the containing folder name!
 
 If you use additional images put them into the `my-page`-folder.
 
+### Add web meta information
+
+If the notebook result should appear as a page on the web documentation a frontmatter with some meta information (similar to [regular web pages]({{< ref "web-docs.md" >}})) is required as the first cell in the notebook:
+
+- Add a new cell and move it to the first position in the notebook
+- Change the cell type to `raw`!
+- Add meta information, conclude with a end-of-file marker (`<!--eofm-->`) e.g.:
+
+  ```md
+  title = "BHE Meshing"
+  date = "2023-08-18"
+  author = "Joy Brato Shil, Haibing Shao"
+  <!--eofm-->
+  ```
+
+---
+
 Make sure that you execute the cells in the notebook and save the notebook (with generated outputs).
 
+### Preview locally
+
 To get a preview of the web page run the `convert_notebooks`-script:
 
 ```bash
 # You need the converter-tool nb2hugo installed. Recommended way is to
 # create and activate a virtual environment and install it there:
-python -m venv .venv
+python -m venv .venv  # or `python3 -m ...` on some systems
 pip install git+https://github.com/bilke/nb2hugo@ogs
 
+python web/scripts/convert_notebooks.py
+
 cd web
-python scripts/convert_notebooks.py
 hugo server
 # open http://localhost:1313
 ```
@@ -43,6 +72,8 @@ Also make sure that you also provide necessary data files and please don't use m
 
 ## 2. Executed notebooks
 
+These notebooks are part of the regular CI testing. Please try to keep the notebook execution time low.
+
 ### Create a new notebook
 
 Create a new notebook file in `Tests/Data` (either as regular `.ipynb`-files or as Markdown-based notebooks via [Jupytext](https://jupytext.readthedocs.io/en/latest)). See examples:
@@ -67,6 +98,8 @@ If the notebook result should appear as a page on the web documentation a frontm
   <!--eofm-->
   ```
 
+`web_subsection` needs to be set to a sub-folder in [web/content/docs/benchmarks](https://gitlab.opengeosys.org/ogs/ogs/-/tree/master/web/content/docs/benchmarks) (if not set the notebook page will not be linked from navigation bar / benchmark gallery on the web page).
+
 <div class='note'>
 
 In Jupytext-based notebooks you can add the frontmatter within the `<!-- #raw -->`- and `<!-- #endraw -->`-markers:
@@ -81,8 +114,6 @@ web_subsection = "small-deformations"
 <!-- #endraw -->
 ```
 
-`web_subsection` needs to be set to a sub-folder in [web/content/docs/benchmarks](https://gitlab.opengeosys.org/ogs/ogs/-/tree/master/web/content/docs/benchmarks) (if not set the notebook page will not be linked from navigation bar / benchmark gallery on the web page).
-
 </div>
 
 ### Notebook setup
@@ -142,7 +173,7 @@ jupyter lab                                # Starts Jupyter Lab
 
 ### Register with CTest
 
-Add the notebook to CTest with e.g.:
+Add the notebook to CTest ([example](https://gitlab.opengeosys.org/ogs/ogs/-/blob/master/ProcessLib/SmallDeformation/Tests.cmake#L272-281)) with e.g.:
 
 ```cmake
 if(NOT OGS_USE_PETSC)