Refactor of contribute pages

_data/sidebars/contribute.yml

@@ -2,6 +2,7 @@ title: Contribute
 title_url: /how_to_contribute
 subitems:
   - title: Ways to contribute
+    url: /ways_to_contribute
     subitems:
       - title: GitHub way
         url: /github_way

pages/contribute/copyright.md

@@ -1,5 +1,6 @@
 ---
 title: Copyright guidelines
+toc: false
 ---
 
 This website aims to be unique and authoritative, but do feel free to include quotes and images from other resources if they add value to the page. Please follow the guidelines below if you do so and respect copyright. 
@@ -18,16 +19,16 @@ Please do not copy the text and tweak the wording slightly. If you are not givin
 
 ## Images
 
-**It is your responsibility to make sure you have permission to use the images you put on the website.**
+**It is your responsibility to ensure you have permission to use the images you put on the website.**
 
-The great majority of images on the web are copyrighted. This includes images on social media, even if they have been reposted or shared. Please make sure you have permission to use them before including them on the website, ideally in writing. If you are not sure whether you can use them, assume that you do not have permission, and contact the copyright owner. 
+The great majority of images on the web are copyrighted. This includes images on social media, even if they have been reposted or shared. Please ensure you have permission to use them before including them on the website, ideally in writing. If you are not sure whether you can use them, assume that you do not have permission and contact the copyright owner. 
 
 If you are using an image with a [Creative Commons license](https://creativecommons.org/licenses/), remember you still need to attribute the creator in accordance with the license.
 
-If you are using a stock image you have bought, or a royalty-free image, check the image license to make sure that you can use it on the RDMkit website. If you are using images provided by your institute or organisation, please also check that you can use them on this site.
+If you are using a stock image you have bought or a royalty-free image, check the image license to make sure that you can use it on the RDMkit website. If you use images provided by your institute or organisation, please also check that you can use them on this site.
 
-You are welcome to create the images yourself, but please follow the [site style guide](style_guide), and bear in mind the image may be modified to better suite the style of the site. The content of the site is published under the [Creative Commons 4 license](https://creativecommons.org/licenses/by/4.0/).
+You are welcome to create the images yourself, but please follow the [site style guide](style_guide) and bear in mind the image may be modified to better suit the style of the site. The content of the site is published under the [Creative Commons 4 license](https://creativecommons.org/licenses/by/4.0/).
 
-If you think an image would be helpful to explain your content but you cannot find the right one, then [create a new issue](https://github.com/elixir-europe/rdmkit/issues) to suggest a new image.
+If you think an image would be helpful to explain your content, but you cannot find the right one, then [create a new issue](https://github.com/elixir-europe/rdmkit/issues) to suggest a new image.
 
 

pages/contribute/editors_checklist.md

@@ -4,7 +4,7 @@ summary: Checklist for editors before approving and merging a pull request (PR).
 ---
 
 ## Before approving and merging a pull request (PR), the editors must check that
-1. The page layout in preview looks correct.
+1. The page layout in the preview looks correct.
 2. The new page is linked in the appropriate [sidebar](https://github.com/elixir-europe/rdmkit/tree/master/_data/sidebars) menu, in the same branch of the PR.
 3. The contributors' names are listed in the [CONTRIBUTORS file](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml), in the same branch of the PR. Advice to have at least one  contributor per page having its contact information in this  [CONTRIBUTORS file](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml).
 4. All relevant metadata fields in a specific page are correctly filled in (see the [page metadata](page_metadata) and the [Editorial board guide](editorial_board_guide)). Some critical ones are listed below.
@@ -19,9 +19,9 @@ summary: Checklist for editors before approving and merging a pull request (PR).
    * `resources`
 5. Make sure that listed tools or resources are tagged in the text with the [correct snippet](tool_resource_update) + that its metadata is described in the [tool_and_resource_list.yml](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml) file. 
 6. Check if relevant recipes on FAIR Cookbook can be linked to the RDMkit page that is being added/changed ([Linking from RDMkit to FAIR Cookbook](editorial_board_guide#linking-from-rdmkit-to-fair-cookbook)).
-7. The content is conform to RDMkit scope, [style](style_guide) and templates.
+7. The content conforms to RDMkit scope, [style](style_guide) and templates.
 8. There are no [copyright](copyright) issues related to the content of the page.
 9. The contributors implemented the requested changes.
 10. When a new page is added, a news item is added to the [news.yml file](https://github.com/elixir-europe/rdmkit/blob/master/_data/news.yml), in the same branch of the PR.
-11. The contributors are thanked for their effort and informed about the publication of their content.
-12. The PR is linked to related issues and can be merged in main branch with no conflicts.
+11. The contributors are acknowledged for their efforts and informed about the publication of their content.
+12. The PR is linked to related issues and can be merged into the main branch with no conflicts.

pages/contribute/github_way.md

@@ -1,70 +1,77 @@
 ---
-title: GitHub way
+title: GitHub way (beginner)
+toc: false
 ---
 
 
-This guide tells you how you can easily request and edit a page on this website. You do this using GitHub. For other ways of contributing, see [How to contribute](how_to_contribute).
+This guide tells you how to request and edit a page using GitHub.
 
+Prerequisites:
+* No technical knowledge
+* A GitHub account. If you do not have one, [create a free GitHub account](https://github.com/join) before you start.
 
-**Prerequisite:** [create a GitHub account](https://github.com/join) before you start. It's easy and free.
 
-## Announce and discuss your proposal through GitHub "issues"
+## Announce and discuss your proposal through GitHub “issues”
+
 1. Go to the [RDMkit repo](https://github.com/elixir-europe/rdmkit) on GitHub.
-2. Click on "Issues" in the top menu bar and look at the existing issues. See if your idea or suggestion is already being discussed.
-      * **If an issue exists**, add your comments. If you want to edit the content discussed, let people know through the comments.
-      * **If no relevant issue exists**, create a new issue by clicking on the green "New issue" button on the right, and choose one of the issues templates. You can find more information on creating issues in the [GitHub documentation](https://docs.github.com/en/github/managing-your-work-on-github/creating-an-issue).
-3. Discuss your idea with the editors through comments in the issues. You will be notified when others comment on your issues. Read the comments and write your opinion/questions/answers in the "Leave a comment" box and click on the green "Comment" button on the right.
-4. You can always return to your opened issue by going to the [issues section](https://github.com/elixir-europe/rdmkit/issues) of our GitHub repo.
-
-{% include callout.html type="tip" content="You can also get to the [RDMkit pages](https://github.com/elixir-europe/rdmkit) on GitHub using the 'GitHub' link in the header of this site" %}
-
-## Write your content and make a pull request
-
-1. When you and the editors have agreed on what you will do, go to the page you want to edit on the website. Click on "Edit me" pencil icon :pencil:, shown next to the page title. If you want to add a new page, the editors will give you the link to the page via comments in the issue you created. The page will come with a predefined template, based on the kind of content you want to contribute.
-1. The "Edit me" pencil icon will take you to the GitHub repository, where you again click on the pencil icon, shown on the right, and start editing.
-   {% include image.html file="raw_github.png" inline=true alt="Editing a page on GitHub" %}
-1. You can now edit or add new text and images according to the provided template. GitHub provide a [guide for writing and formatting in GitHub](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github). We also provide a [markdown cheat sheet](markdown_cheat_sheet) to show you how to write in this webpage. Make sure to read our [style guide](style_guide) before start writing. In general, try to avoid manual interlinking of RDMkit pages.
-1. If you have mentioned tools or resources in your text, make sure to add them to the [tool and resource list](tool_resource_update). If you want to list training material in your page, add it to the metadata of the page, according to the training matadata fields provided in the page template.
-1. When you are happy with your first draft of the content, go to the “Propose changes” section at the end of the page and write a title and a brief explanation of your changes.
-1. Click on “Propose changes”.
-   {% include image.html file="propose_changes_github.png" inline=true alt="Propose changes on GitHub" %}
-1. You are now redirected to the Pull Request (PR) page. A "pull request" is a request to "pull" your changes into the website. Click on the "Create Pull Request" green button. Here you can choose to:
-     * "Create draft pull request": choose this if you have not finished writing. Later on you can always click on "Ready for review" to switch to a normal pull request. You can find more information about draft pull requests in the [GitHub documentation](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests).
-     * "Create pull request": choose this if you have finished your text. Editors will then review your request.
-       {% include image.html file="draft_pullrequest_github.png" inline=true alt="PrDraft pull request on GitHub" %}
-
-1. In the description of your pull request you can link to the issue that relates to this change by typing a hashtag `#` and the correct issue number. Suggestions will appear. This way it is easy for the editors to link back the issue were this change might have been discussed beforehand.
-    {% include image.html file="linking_issues_github.png" inline=true alt="Linking issues in a pull request on GitHub" %}
-
-1. You can return to your pull request by going to the [pull request section](https://github.com/elixir-europe/rdmkit/pulls) of our GitHub repo.
-
-1. If you change your mind about anything in your pull request and the request is not closed, or if the editor tells you to edit your request during the review process, you have to:
-    * Go to your pull request
-    * Click on "Files changed" in the top menu bar.
-      {% include image.html file="files_changed_github.png" inline=true alt="Files changed tab on GitHub" %}
-    * Click on the icon with 3 dots "..." of the file you  want to edit and then click on "Edit file".
-      {% include image.html file="3_dots_github.png" inline=true alt="File change options on GitHub" %}
-    * Make your changes.
-    * Click on “Commit changes”.
-
-{% include callout.html type="note" content="Anyone can comment on your issue or pull request and you can reply. For more information on this, please visit the [GitHub documentation](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)" %}
-
-## Request a review
-
-If you open a normal pull request then a review is automatically requested. The relevant editors will check your changes. If your request is still in draft, click on "Ready for review" to request a review. You can find more information about draft pull requests in the [GitHub documentation](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review).
-
-## Address editors' comments
-
-1. When editors add comments or add a review of your pull request, you will be notified.
-1. You need to address editors' comments and requests by editing your pull request as in step 7 (see above).
-   * Go to your pull request
-   * Click on "Files changed" in the top menu bar.
-     {% include image.html file="files_changed_github.png" inline=true alt="Files changed tab on GitHub" %}
-   * Click on the icon with 3 dots "..." of the file you  want to edit and then click on "Edit file".
-     {% include image.html file="3_dots_github.png" inline=true alt="File change options on GitHub" %}
-   * Make your changes.
-   * Click on “Commit changes”.
-
-1. When all the requests have been addressed, the editors will mark the conversation as "Resolved" and the proposed changes as "Approved".
-1. You content is ready to be merged and published in the main website.
-1. Editors publish your content.
+2. Click “Issues” in the top menu bar and look at the existing issues. See if your idea or suggestion is already being discussed.
+    * If an issue exists, comment and let people know if you want to contribute.
+    * If no relevant issue exists, create a new issue by clicking the green “New issue” button on the right and choosing one of the issue templates. You can find more information on creating issues in the [GitHub documentation](https://docs.github.com/en/github/managing-your-work-on-github/creating-an-issue).
+
+3. Discuss your idea with the editors through comments in the issues – you will be notified when others comment.
+    * You can read the comments and write your opinion/questions/answers in the “Leave a comment” box. To submit your responses, click the green “Comment” button on the right.
+    * You can always return to your opened issue by going to the [issues section](https://github.com/elixir-europe/rdmkit/issues) of our GitHub repo.
+
+{% include callout.html type="tip" content="You can also get to the [RDMkit ](https://github.com/elixir-europe/rdmkit)repo on GitHub using the ‘GitHub’ link in the header of this site." %}
+
+
+## Read the guides {#read-the-guides}
+
+Before starting editing on GitHub:
+1. Make sure you are following our [style guide](https://rdmkit.elixir-europe.org/style_guide).
+2. Follow the structure of the provided template for the page you wish to create or update. 
+3. We use markdown. To know how to create paragraphs, headings, format text, add links and images and much more, follow our [markdown cheat sheet](https://rdmkit.elixir-europe.org/markdown_cheat_sheet).
+
+{% include callout.html type="tip" content="For more information on writing and formatting, visit [GitHub’s documentation](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github)." %}
+
+
+## Start editing {#start-editing}
+{% include callout.html type="important" content="Only move to the following steps if you and the editors have agreed on your plans and you have read the guides.
+" %}
+
+1. Find where to edit on GitHub
+    * If you want to contribute to an existing page, go to the page on the site and click the “Edit me” pencil icon 
+    * If you want to create a new page, the editors will provide a link to the page as a comment in your GitHub issue. The page will come with a predefined template based on the kind of content you want to contribute.
+2. You will be taken to the correct GitHub repository, where you will look for a pencil icon on the top right.
+
+## Linking resources and other pages (optional)
+* If you have mentioned tools or resources in your text, you will have to add them to the [tool and resource list](https://rdmkit.elixir-europe.org/tool_resource_update).
+* If you want to list training material, add it to the page metadata. This is the training fields that are part of the template, provided at the top of the page.
+
+{% include callout.html type="important" content="In general terms, you must avoid manual interlinking of RDMkit pages." %}
+
+
+## Submit your first draft
+
+1. When you are happy with your first draft, go to the “Propose changes” section at the end of the page and write a title and a brief explanation of your changes.
+2. Click “Propose changes”. 
+3. Create a pull request following [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+
+
+{% include callout.html type="tip" content="You can create a draft pull request when you're not ready to submit and will need to work more on it later. You can find more information about draft pull requests in the [GitHub documentation](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests)" %}
+
+
+4. In the description of your pull request, link the issue related to this change by typing a hashtag # and the issue number. Suggestions will appear.
+
+
+{% include callout.html type="tip" content="You can return to your pull request by going to the [pull request section](https://github.com/elixir-europe/rdmkit/pulls) of our GitHub repo." %}
+
+
+## Address editors' reviews by editing your pull request
+When editors add comments or add a review of your pull request, you will be notified. To address comments, you must edit your pull request:
+1. Go to your pull request. You can return to it by going to the [pull request section](https://github.com/elixir-europe/rdmkit/pulls) of our GitHub repo
+2. Follow [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) to make edits. 
+
+When all the requests have been addressed, the editors will mark the conversation as “Resolved” and the proposed changes as “Approved”. This means your content is ready to be published on the main website.
+
+{% include callout.html type="tip" content="You can also edit your pull request any time if you change your mind about anything in your pull request and the request is not closed yet." %}