Merge pull request #17 from cpp-lln-lab/fcerpe-patch-1

imporved readability

Author: fcerpe

doc/contributing.md

@@ -1,33 +1,40 @@
 # CONTRIBUTING
 
-Something is not clear or incorrenct or incomplete, something needs some updates over time or you found something new and cool that absolutely needs to be shared with the others... please contribute to this docs!!!
+This is a common effort, please contribute actively to this docs.
+If something is unclear, incorrect, or incomplete; if something needs to be updated or if you found a new and cool feature, consider adding it yourself.
+Here's a short guidelines on how to do so.
 
-## Submit an issue (no git/github skills required)
 
-Open an issue from [here](https://github.com/cpp-lln-lab/CPP_LabGuide/issues/new/choose) and try to be the most detailed possible.
+## Submit an issue (no git/github skills required)
 
-## Make the changes your self (minor git/github skills required)
+Open an issue from [here](https://github.com/cpp-lln-lab/CPP_LabGuide/issues/new/choose).
+Try to be the most detailed possible, so it's easier to intervene.
 
-The actual text/scripts you find in this website are in this [repo](https://github.com/cpp-lln-lab/CPP_LabGuide) and in the `doc` folder [here](https://github.com/cpp-lln-lab/CPP_LabGuide/tree/main/doc)
 
-Each article/section of the website is a specific markdown file with the same transparent name (more or less).
+## Make the changes yourself (minor git/github skills required)
 
-### Edit from github
+The actual text/scripts you find in this website are in this [repoistory](https://github.com/cpp-lln-lab/CPP_LabGuide) and in the `/doc` folder [here](https://github.com/cpp-lln-lab/CPP_HPC/tree/main/doc).
+Each article/section of the website is a specific markdown (`.md`) file with (more or less) the same transparent name.
 
-Just find the the markdown file you want to edit (eg the one for this section [contributing.md](https://github.com/cpp-lln-lab/CPP_LabGuide/blob/main/doc/contributing.md)) and click on `edit` (the pen icon) on the top right.
+If you're new to markdown, here's a quick [markdown cheatsheet](https://www.markdownguide.org/cheat-sheet/).
 
-When done, click on `commit changes` (green botton on the top right) and select `Create a new branch for this commit and start a pull request` and then `Commit changes`.
 
-On the new opened page you can edit the title of the pull request to provide a more meaningful one, select a reviewer (highly reccomended!!!) and then finally create the pull request (PR).
+### Edit from github
 
-If you fill confident you can then merge it right away or ask someone else to review the PR and then approve it with or without corrections and merge it.
+1. Browse the repo to find the the markdown file you want to edit (e.g. the one for this section is [contributing.md](https://github.com/cpp-lln-lab/CPP_HPC/blob/main/doc/contributing.md)) and click on `edit` (the pen icon) on the top right
+2. Edit the file with your changes
+3. When done, click on `commit changes` (green botton on the top right), select `Create a new branch for this commit and start a Pull Request`, and then `Commit changes`
+4. On the new opened page, edit the Pull Request's title to provide more information (a few words, not an essay)
+5. Select a reviewer (e.g. [Filippo Cerpelloni](https://github.com/fcerpe) or [Marco Barilari](https://github.com/marcobarilari)). The review process helps preventing unnecessary / unwanted changes.
+6. Create the Pull Request (PR).
 
-To change the website strucute (change name to section, add sections or reorder them), see the file `mkdocs.yml` section `Pages`.
+To change the website structure (add, reorder, rename sections), see the file `mkdocs.yml` and the section `Pages`.
 
-That's it!
 
 ### Edit locally
 
+If you're unfamiliar with the terms used here, check out the [git cheatsheet](https://training.github.com/downloads/github-git-cheat-sheet/)
+
 1. fork this repository
 2. clone your forked repository
 3. install the dependencies via: