Improving contributing guide

docs/contributing/index.md

@@ -7,7 +7,7 @@
 
 We use the GitHub fork and pull request model for development:
 
-* First create a fork of the [main GitHub repository](https://github.com/eth-cscs/cscs-docs).
+* First create a [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) of the [main GitHub repository](https://github.com/eth-cscs/cscs-docs).
 * Make all proposed changes in branches on your fork - don't make branches on the main repository (we reserve the right to block creating branches on the main repository).
 
 Clone your fork repository on your PC/laptop:
@@ -18,41 +18,50 @@
 # create a branch for your changes (here we are fixing the ssh docs)
 git switch -c 'fix/ssh-alias'
 # ... make your edits ...
-# add and commit your changes
-git add <files>
-git commit -m 'update the ssh docs with aliases for all user lab vclusters'
-git push origin 'fix/ssh-alias'
 ```
-Then navigate to GitHub, and create a pull request.
 
-The `serve` script in the root path of the repository can be used to view the docs locally:
+Review your edits checking the [Guidelines](#guidelines) section below.
+
+!!! note
+    Note that a simple editor markdown preview may not render all the features of the documentation.
+
+To properly review the docs locally, the `serve` script in the root path of the repository can be used as shown below:
 ```bash
 ./serve
 ...
 INFO    -  [08:33:34] Serving on http://127.0.0.1:8000/
 ```
-This generates the documentation locally, which can be viewed using a local link, which is `http://127.0.0.1:8000/` by default.
-The documentation will be rebuilt and the webpage reloaded when changed files are saved.
 
 !!! note
     To run the serve script, you need to first install [uv](https://docs.astral.sh/uv/getting-started/installation/).
 
-To build the docs in a `site` sub-directory:
+You can now open your browser at the address shown above (`http://127.0.0.1:8000/`). The documentation will be automatically rebuilt and the webpage reloaded on each file change you save.
+
+Alternatively, you can build the docs in a `site` sub-directory and open `site/index.html` with your browser too.
+
 ```bash
 ./serve build
 ```
 
+After your first review, commit and push your changes
+```bash
+git add <files>
+git commit -m 'update the ssh docs with aliases for all user lab vclusters'
+git push origin 'fix/ssh-alias'
+```
+
+Then navigate to GitHub, and create a pull request.
+
 !!! tip
     If you've already created a fork repository, make sure to [keep it synced](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to the main CSCS repository before making further change.
 
 ## Review process
 
-Documentation is owned by everybody - so don't be afraid to jump in and make changes or fixes where you see that there is something missing or outdated.
+Documentation is maintained by everybody - so don't be afraid to jump in and make changes or fixes where you see the need or the potential.
 
-If you plan to make large changes or contributions, please discuss them with the documentation owners beforehand, to make sure that the documentation will fit into the larger documentation structure.
+If you plan to make significantly large changes, please discuss them with an [issue](https://github.com/eth-cscs/cscs-docs/issues) beforehand, to ensure the changes will fit into the larger documentation structure.
 
-If the documentation that you write or update might affect multiple stakeholders, ping them for a review.
-If you don't get a timely reply, ask the documentation owners for a review or for permission to merge.
+If you think your documentation update could affect specific stakeholders, ping them for a review. The same applies if you are not getting get a timely reply for your pull request. You can get some hints of whom to contact by looking at [CODEOWNERS](https://github.com/eth-cscs/cscs-docs/blob/main/.github/CODEOWNERS).
 
 !!! note
     To minimise the overhead of the contributing to the documentation and speed up "time-to-published-docs" we do not have a formal review process.
@@ -116,18 +125,60 @@
 
 ### Images
 
+> A picture is worth a thousand words
+
+We encourage the usage of images to improve clarity and understanding. You can use **screenshots** or **diagrams**.
+
 Images are stored in the `docs/images` directory.
 
-* there are sub-directories in the `docs/images` path - create a new sub-directory for your images if appropriate
-* choose image and path names that make sense - `screenshot.png` is not a great file name. Neither is `PX-202502025-imgx.png`.
+* create a new sub-directory for your images if appropriate
+* choose a path and file name that hint what the image is about - neither `screenshot.png` nor `PX-202502025-imgx.png` are great names.
 
-!!! tip
-    When providing a screenshot, do you need to show the whole screen, or just part of one window?
+!!! warning
+    Keep the size of your images to a minimum because we want to keep an overall lightweight repository.
 
-    Cropping the image will decrease file size, and might also draw the readers attention to the most relevant information.
 
-!!! tip
-    Do you need a screenshot, or can a text description also work?
+#### Screenshots
+
+Screenshots can help readers follow steps on guides. Think if you need to show the whole screen or just part of one window. Cropping the image will decrease file size, and might also draw the readers attention to the most relevant information.
+
+Often, screenshots can quickly become obsolete, so you may want to complement (or maybe even replace) some with text descriptions.
+
+#### Diagrams
+
+Diagrams can help readers understand more abstract concepts like processes or architectures. We suggest you use [mermaid](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams). Such format makes diagrams easy to maintain and removes the need to commit image files in the repository.
+
+??? "Example"
+
+    === "Source"
+
+        ````text
+        ```mermaid
+        graph TD;
+            Image(Will image add value?);
+            Image--NO-->T(keep text only);
+            Image--YES-->SD(What image is needed?)
+            SD--Screenshot-->S(keep it lean)
+            SD--Diagram-->D(keep it maintainable)
+            D--Default-->M(Mermaid)
+            D--Custom-->DR(Draw.io)
+        ```
+        ````
+
+    === "Rendered"
+
+        ```mermaid
+        graph TD;
+            Image(Will image add value?);
+            Image--NO-->T(keep text only);
+            Image--YES-->SD(What image is needed?)
+            SD--Screenshot-->S(keep it lean)
+            SD--Diagram-->D(keep it maintainable)
+            D--Default-->M(Mermaid)
+            D--Custom-->DR(Draw.io)
+        ```
+
+If you need more hand-crafted diagrams, we suggest you use [draw.io](https://www.drawio.com/). Make sure you export the png with the [source inside](https://www.drawio.com/doc/faq/export-to-png), typically a `file.drawio.png`, so it can be extended in the future as needed.
 
 ### Text formatting
 
@@ -230,10 +281,10 @@
 !!! example "Example one"
     This is an example.
     The title of the example uses [sentence case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case).
-    
+
 ??? note "Collapsed note"
     This note is collapsed, because it uses `???`.
-    
+
 If an admonition is collapsed by default, it should have a title.
 
 We provide some custom admonitions.