Merge pull request #9 from psm-compute/small-improvement

small reformulation

docs/source/git.rst

@@ -3,29 +3,45 @@
 GIT tips
 ========
 
-Getting Started with Git and GitHub
------------------------------------
+If you are new to Git and GitHub, this page helps you getting started by explaining
+how to make some modification to a repository. The explaining assumes that you
+are trying to modify this website, but it should work for most repositories.
 
 1. Set Up Your SSH Key
 ______________________
 
-To securely connect with GitHub, you'll need to add your SSH key to your GitHub account. Here you can find how to `add your public key <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_ .
+To securely connect with GitHub, you'll need to add your SSH key to your GitHub
+account. |public_key|, you can find how to add your public key to your account.
+
+.. |public_key| raw:: html
+
+    <a href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account" target="_blank">here</a>
 
 2. Clone a GitHub Repository
 ____________________________
 
-Navigate to the directory where you want to download the repository, then use the :code:`git clone` command:
+If you are not a member of the `psm-compute` organization, fork
+the repository (i.e. create a duplicate of the repository in your own GitHub account),
+then clone it (see below).
+
+If you are a member, natigate to the |repository|, click on `Code`, then copy
+the `SSH` link and clone the repository using  :code:`git clone` : 
+
+.. |repository| raw:: html
+
+   <a href="https://github.com/psm-compute/psm-compute.github.io" target="_blank">here</a>
 
 .. code:: bash
 
     git clone [email protected]:psm-compute/psm-compute.github.io.git
 
-This command will create a copy of the repository in your specified directory.
+This command will create a local copy of the repository on your computer.
 
 3. Check the Status of Your Repository
 ______________________________________
 
-After cloning, it's a good practice to check the status of your repository to see if there are any changes:
+From you computer, when you start making modifications to the files, it's a
+you can check the status of your repository to see if there are any changes:
 
 .. code:: bash
 
@@ -34,18 +50,23 @@ After cloning, it's a good practice to check the status of your repository to se
 4. Create and Switch to a New Branch
 ____________________________________
 
-To make changes without affecting the main branch, create a new branch and switch to it. Let's make a test updating `README.md` file.
+To make changes without affecting the main branch, create a new branch:
 
 .. code:: bash
 
     git branch update_readme
-    git checkout update_readme
 
+and then, switch to the new branch:
+
+.. code:: bash
+
+    git checkout update_readme
 
 5. Edit Files and Stage Changes
 _______________________________
 
-Make the necessary edits to your files. For example, to edit the `README.md` file, use a text editor like `vi`:
+Make the necessary edits to the files. For example, to edit the `README.md` file,
+use a text editor like `vi`:
 
 .. code:: bash
 
@@ -70,15 +91,16 @@ Commit your changes with a descriptive message:
 
 .. code:: bash
 
-    git commit -m "Test change README.md"
+    git commit -m "Modified the README.md file"
 
-Next, push your changes to GitHub. If it's the first time you're pushing from this branch, you'll need to set the upstream branch:
+Next, push your changes to GitHub:
 
 .. code:: bash
 
     git push
 
-If you encounter an error, you'll typically need to set the upstream for the branch:
+If it's the first time you're pushing from this branch, you'll need to set the
+upstream branch:
 
 .. code:: bash
 
@@ -87,19 +109,17 @@ If you encounter an error, you'll typically need to set the upstream for the bra
 7. Create a Pull Request
 ________________________
 
-Finally, open your web browser and navigate to the GitHub page for this project: 
-
-`<https://github.com/psm-compute/psm-compute.github.io>`_
-
-After pushing your changes, you should see a message indicating the recent pushes. Click on **"Compare & pull request"**.
-
-On the right side of the page, select your reviewers, and add a description if needed. This will create a pull request for your changes to be reviewed and merged.
-
+Finally, open your web browser and navigate to the GitHub repository (|repository|): 
+After pushing your changes, you should see a message indicating the recent
+pushes. Click on **"Compare & pull request"**. On the right side of the page,
+select your reviewers, and add a description if needed. This will create a pull
+request for your changes to be reviewed and merged.
 
 8. Delete the Branch Locally (Optional)
 _______________________________________
 
-If you no longer need the branch locally, you can delete it:
+Once your changes are merged with the main branch, and if you no longer need the
+branch locally, you can delete it:
 
 .. code:: bash
 

docs/source/oar.rst

@@ -1,30 +1,18 @@
 OAR tips
 ========
 
-This page collect some tips for running jobs using the OAR system of |GRICAD|.
-Feel free to add your own tricks to the list, or signal us any error.
-
-|GRICAD|
+This page collect some tips and tricks for managing jobs using the OAR system of |GRICAD|.
 
 .. |GRICAD| raw:: html
 
     <a href="https://gricad-doc.univ-grenoble-alpes.fr/hpc/joblaunch/job_management/" target="_blank">GRICAD</a>
 
-Cancel All Your Jobs at Once
-----------------------------
-
-Cancel all your jobs at once by typing:
-
-.. code:: bash
-
-    oarstat -u username | awk '{print $1}' | xargs -n 1 oardel
-
-where username should be replaced by your ID.
-
 Submit Jobs with Dependencies
 -----------------------------
 
-You can submit jobs with dependencies using the following example. Assume you have two job scripts, `job1.sh` and `job2.sh`, that you wish to submit:
+You can submit jobs with dependencies using the following example. Assuming that
+you have two job scripts, `job1.sh` and `job2.sh`, and that you wish to submit
+`job2.sh` `after` `job1.sh` is done.
 
 1. Submit `job1.sh` and capture its job ID:
 
@@ -38,6 +26,17 @@ You can submit jobs with dependencies using the following example. Assume you ha
 
       oarsub -S ./job2.sh  -a $job1_id
 
-In this example, `job2.sh` will automatically wait for `job1.sh` to complete
-before starting, using the job ID captured in `job1_id`.
+In this example, `job2.sh` will wait for `job1.sh` to complete
+before starting, using the job ID (`job1_id`).
+
+Cancel All Your Jobs at Once
+----------------------------
+
+You can cancel all your jobs at once by typing:
+
+.. code:: bash
+
+    oarstat -u username | awk '{print $1}' | xargs -n 1 oardel
+
+where username should be replaced by your ID.