diff --git a/_data/CONTRIBUTORS.yaml b/_data/CONTRIBUTORS.yaml index f008d53c8..b1cec787c 100755 --- a/_data/CONTRIBUTORS.yaml +++ b/_data/CONTRIBUTORS.yaml @@ -638,4 +638,7 @@ Magda Chegkazi: affiliation: ELIXIR Arshiya Merchant: email: arshiya.merchant@elixir-europe.org - affiliation: ELIXIR + affiliation: ELIXIR +Xènia Pérez Sitjà: + affiliation: Earlham Institute / ELIXIR-UK + git: sitjart diff --git a/_data/sidebars/contribute.yml b/_data/sidebars/contribute.yml index cb583cee0..f640d71e0 100644 --- a/_data/sidebars/contribute.yml +++ b/_data/sidebars/contribute.yml @@ -5,7 +5,7 @@ subitems: subitems: - title: GitHub way url: /github_way - - title: Google doc way + - title: Google Docs way url: /google_doc_way - title: Git way (advanced) url: /working_with_git diff --git a/_sass/_custom_classes.scss b/_sass/_custom_classes.scss index 9cd42c7c3..e3e2568d1 100644 --- a/_sass/_custom_classes.scss +++ b/_sass/_custom_classes.scss @@ -94,20 +94,7 @@ /* -----Homepage----- */ -.landingpage { - .h-icon-8 { - height: 8em; - } - .h-icon-6 { - height: 6em; - } - .h-icon-5 { - height: 5em; - } - .h-icon-4 { - height: 4em; - } - +.landingpage, .ways-to-contribute { .card { &:hover { box-shadow: $box-shadow; @@ -136,6 +123,21 @@ } } +// Icon sizing + +.h-icon-8 { + height: 8em; +} +.h-icon-6 { + height: 6em; +} +.h-icon-5 { + height: 5em; +} +.h-icon-4 { + height: 4em; +} + // Search box section#search-section { diff --git a/pages/contribute/copyright.md b/pages/contribute/copyright.md index 8198f36d8..08cacb61c 100644 --- a/pages/contribute/copyright.md +++ b/pages/contribute/copyright.md @@ -18,16 +18,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. diff --git a/pages/contribute/editorial_board_guide.md b/pages/contribute/editorial_board_guide.md index 22dd93476..3ec407699 100644 --- a/pages/contribute/editorial_board_guide.md +++ b/pages/contribute/editorial_board_guide.md @@ -166,7 +166,7 @@ If the markdown page is named example_1.md, you can link towards it using: ## Adding extra info to the contributors -Do you want that the GitHub picture of a contributor is shown next to their name? Or maybe you want that the name is clickable and links towards the GitHub page of that person? To enable this please add the name and the necessary metadata to the [CONTRIBUTORS.yaml](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml) file in the *_data* directory like this: +It is strongly recommended to let the contributors fill in their ORCID and email address. This can be added together with the name, affiliation and GitHub ID to the [CONTRIBUTORS.yaml](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml) file in the *_data* directory like this: ```yaml Bert Droesbeke: @@ -176,7 +176,7 @@ Bert Droesbeke: role: editor affiliation: VIB Data Core / ELIXIR-BE ``` -{% include callout.html type="important" content="Make sure that the name in the yaml file is identically the same as the one used in the metadata of the page." %} +{% include callout.html type="important" content="Make sure that the name of the contributor in the yaml file is identical as the one used in the metadata of the page." %} ## Adding an institution, infrastructure, project or funder diff --git a/pages/contribute/editors_checklist.md b/pages/contribute/editors_checklist.md index c812fdff8..33a09ac6d 100644 --- a/pages/contribute/editors_checklist.md +++ b/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's 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. diff --git a/pages/contribute/github_way.md b/pages/contribute/github_way.md index 075476862..902ad4d72 100644 --- a/pages/contribute/github_way.md +++ b/pages/contribute/github_way.md @@ -3,68 +3,80 @@ title: GitHub way --- -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: +* Basic knowledge of Markdown. All you need to know is in our [markdown cheat sheet](markdown_cheat_sheet) +* 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 a GitHub Issue + 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. +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 one: click the green “New issue” button on the right and choose a template. 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 + +Before starting editing on GitHub: +1. Make sure you are following our [style guide](style_guide). +2. Follow the structure of the provided template for the page you wish to create or update. +3. We use markdown. To learn 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). +4. Our pages contain metadata. Read more about them in our [page metadata guide](page_metadata). + +{% 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)." %} -{% 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 +## 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. 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. +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 next to the page title + * 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. {% 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”. +## 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](tool_resource_update). +* If you want to list training material or link to other RDMkit pages, add it to the page metadata. Read more on how to do this in our [page metadata guide](page_metadata). + +{% include callout.html type="important" content="In general terms, you must avoid manual interlinking of RDMkit pages." %} -{% 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 +## Submit your first draft -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). +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. + {% include image.html file="propose_changes_github.png" inline=true alt="Propose changes on GitHub" %} +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 image.html file="draft_pullrequest_github.png" inline=true alt="PrDraft pull request on GitHub" %} +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 image.html file="linking_issues_github.png" inline=true alt="Linking issues in a pull request on GitHub" %} +{% 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)" %} +{% 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' 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. +## 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. * 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. +3. 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) for more information. + +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." %} diff --git a/pages/contribute/google_doc_way.md b/pages/contribute/google_doc_way.md index 4b758468a..c54b5b071 100644 --- a/pages/contribute/google_doc_way.md +++ b/pages/contribute/google_doc_way.md @@ -1,24 +1,26 @@ --- -title: Google doc way +title: Google Docs way --- +This guide tells you how to request and edit a page using Google Docs. -## Contribution process +Prerequisites: +* A Google account -RDMkit is hosted on GitHub. We understand, however, that many people may be unfamiliar or inexperienced with git. We therefore provide the Google doc option for contributing. -The steps are as follows: -* Email the editorial team at [rdm-editors@elixir-europe.org](mailto:rdm-editors@elixir-europe.org) to propose a new page or a new section in an existing page. Make sure you keep other contributors in the CC of your email. The editors will create an issue in our GitHub repository to announce your contribution to others. -* Use our section specifc google doc templates to write your page: +## Follow the steps below to contribute using Google Docs + +1. Email the editorial team at [rdm-editors@elixir-europe.org](mailto:rdm-editors@elixir-europe.org) to propose additions or updates to an existing page. Make sure you keep other contributors in CC. +2. Use our section-specific Google Doc templates to write your page: * [Your task template](https://docs.google.com/document/d/11MsyGl7WJXI4dahMjbI3addEXQlpDzM19Yk_6e-gsVI) * [Your domain template](https://docs.google.com/document/d/1fh8-Gq50AkXS1nhHr-gVFog-eI61dFI49nKROZlRYEQ) * [Your role template](https://docs.google.com/document/d/1J8SmHw-TtVQ6P38SzucRB37upYwscUOwbTx_qllOPaI) * [Tools assembly template](https://docs.google.com/document/d/1BZsc647JAmJwUkVjds5cu52_-70_TTfDMypPHqDiFrM) * [National resources template](https://docs.google.com/document/d/1icB57BHMbZbxwFV9keq9ZYm5QbrDjJDeufrTdoYmHzk) -* Notify the editorial team when you are finished. -* The editors will assign reviewers to your page, who will provide feedback as comments on the shared google doc. -* Address the reviewers' comments and let the editorial team know, again by mail, that you're finished with revisions. -* The editors will transfer your page to GitHub and let you know when it is published on the website. +3. Notify the editorial team when you are finished. +4. Read the feedback that the reviewers will provide as comments on the shared Google document. +5. Address the reviewers’ comments and let the editorial team know when you are finished. +6. Receive notification from the editors when your contributions are live. diff --git a/pages/contribute/how_to_contribute.md b/pages/contribute/how_to_contribute.md index 8933dfc48..1cead0bfb 100644 --- a/pages/contribute/how_to_contribute.md +++ b/pages/contribute/how_to_contribute.md @@ -2,38 +2,60 @@ title: How to contribute to RDMkit --- -## Ways of contributing - -Everyone is welcome to contribute to this site, and we've tried to make it as easy as possible. Choose a way that suits you. The website is hosted on GitHub, so: - -* **If you are not familiar with Git** but want to give it a try on GitHub: follow [our step-by-step instructions](github_way) (no technical knowledge required!). -* **If you are happier using Google Docs**: follow [the Google Doc way](google_doc_way). -* **If you are familiar with Git**: fork the repo and create a pull request (see our [instructions](working_with_git)). -* **If you just want to make a quick suggestion**: submit your comments/suggestions using the form below. - -## Contributor responsibilities - -When writing for this website keep in mind the following: +This project is only possible with the many [community contributors](contributors). RDMkit is an open project where everyone can contribute to the site. -* For the sake of consistency, please follow our [style guide](style_guide). -* It is your responsibility to make sure that the content you provide respects copyright. Please follow our [Copyright guidelines](copyright). -* Please read our [Markdown cheat sheet](markdown_cheat_sheet) in order to be able to fill in the page metadata and to format the layout correctly. -* To avoid having to resolve many issues during the revision process, please check the [Editors checklist](editors_checklist) and make sure you have complied with the requirements. -* If others were involved in your contribution, by writing up or by providing resources such as diagrams or links, please make sure you acknowledge them in the contributors' section of your page, after receiving their permission. +If you wish to contribute, please remember the following: -## Acknowledgement of contributors +* Follow our [style guide](style_guide). +* Ensure your content respects copyright. Please follow our [Copyright guidelines](copyright). +* Acknowledge [contributions](#acknowledgement-and-ownership-of-content) of yourself and other contributors. -Contributors will be shown at the bottom of the page if listed in the metadata of the markdown file. All contributors will also be displayed in the [contributors page](contributors). If you want to link your GitHub account, ORCID or email address, please add your name and corresponding information to the [CONTRIBUTORS file](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml). -## Ownership of content - -No single contributor or editor owns the content of the site, or has the right to dictate what the content should be. The content on the RDMkit is a community effort, with many people contributing. Decisions are driven by consensus among the contributors and editors. +## Ways of contributing -The content is periodically updated, which means that if you create content in an RDMkit page, others can change the content without notifying you. However, the RDMkit editors ensure that content is only modified for good reasons. The RDMkit editors try to ensure that the legitimate concerns and different point of views of all contributors are accommodated, and that the content reflects the most popular consensus on any given topic. +
+
+
+ GitHub Icon +
+ +

GitHub

+ +

Contribute to the content directly using Markdown templates.

+
+
+
+
+
+ Google Docs icon +
+ +

Google Docs

+ +

If you are unfamiliar with Git and prefer to use a Word-like editor.

+
+
+
+
+
+ Git Icon +
+ +

Git

+ +

If you are familiar with Git, fork the repo and create a pull request.

+
+
+
+
+ + +## Acknowledgement and ownership of content + +Contributors will be shown at the bottom of each page and on the main [contributors page](https://rdmkit.elixir-europe.org/contributors) if listed in the metadata of the markdown file. We strongly suggest to add the name, ORCID, email address and/or GitHub account and affiliation of the contributor to the [CONTRIBUTORS file](https://github.com/elixir-europe/rdmkit/blob/master/_data/CONTRIBUTORS.yaml). + +No single contributor or editor owns the site's content or has the right to dictate what the content should be. The content on the RDMkit is community-led, with many people contributing to each section. Hence, decisions are driven by consensus among the contributors and editors. + +Since content is periodically updated, others may change your contribution without notifying you. However, the RDMkit editors ensure that content is only modified for good reasons, ensuring that all legitimate concerns and different points of view are accommodated and that the content reflects the most popular consensus on any given topic. If you find any content unsatisfactory, please feel free to [create an issue](https://github.com/elixir-europe/rdmkit/issues/new/choose) about it. - - -## Making a quick suggestion - - diff --git a/pages/contribute/preview_changes.md b/pages/contribute/preview_changes.md index 74ed86d5e..aaea77705 100644 --- a/pages/contribute/preview_changes.md +++ b/pages/contribute/preview_changes.md @@ -14,19 +14,19 @@ As an editor with editing rights, changes made by clicking on the pencil icon wi ### 1. Make sure you have forked the main branch -Click on the 'fork' button in the right top corner to find out. If a fork is present under your personal GitHub ID, click on it. +Click on the 'fork' button in the top right corner to find out. If a fork is present under your personal GitHub ID, click on it. {% include image.html file="your_own_fork.png" alt="Your own fork" %} -Make sure you are in the `main` branch of your fork seen in the left top corner. +Make sure you are in the `main` branch of your fork, seen in the left top corner. {% include image.html file="change_branch.png" alt="Change branch on GitHUb" %} ### 2. Make sure your fork is up to date -Click on the 'sync fork' button to make sure you have the latest changes of the main branch in your fork. 'Update branch'. +Click on the 'sync fork' button to ensure you have the latest changes of the main branch in your fork. 'Update branch'. {% include image.html file="sync_branch.png" alt="Click on the sync fork button." %} @@ -51,9 +51,9 @@ This step is important. Make sure to commit to a new feature branch which you na {% include image.html file="deploy_using_gh_actions.png" alt="Got to the settings tab in your repo to enable GitHub pages" %} -## Open a Pull Request (PR) with you changes +## Open a Pull Request (PR) with your changes -Got to your newly created branch and click 'Contribute'. This will create a PR to the main repository. +Got to your newly created branch and click 'Contribute'. This will create a PR for the main repository. {% include image.html file="create_pr_from_fork.png" alt="Create new PR from fork." %} diff --git a/pages/contribute/style_guide.md b/pages/contribute/style_guide.md index 8a13899b9..78ce83709 100644 --- a/pages/contribute/style_guide.md +++ b/pages/contribute/style_guide.md @@ -13,38 +13,42 @@ In general, we follow the European Commission's [Web Writing Style Guide](https: ## Text * **Acronyms:** spell them out the first time. - * **Ampersands:** do not use these in the main text or headings. It is fine to use them in menus, if you need to save space. + * **Ampersands:** do not use these in the main text or headings. It is fine to use them in menus if you need to save space. * **Capitals:** do not use all capitals for emphasis or in headings. * **Data:** treat as singular ("Data is..."). (Whether "data" is singular or plural is contentious - see the [Wikipedia article](https://en.wikipedia.org/wiki/Data_(word)) and this [Guardian article](https://www.theguardian.com/news/datablog/2010/jul/16/data-plural-singular).) * **Dates:** use Wednesday 7 July 2021 (not Wednesday 7th July 2021, or other variations). * **Datasets:** not "data sets". * **Email:** not "e-mail". - * **Email addresses:** spell these out and make the email address the link e.g. [rdm-toolkit@elixir-europe.org](mailto:rdm-toolkit@elixir-europe.org). Do not hide the email address behind a word or phrase like "contact us". + * **Email addresses:** spell these out and make the email address the link, e.g. [rdm-toolkit@elixir-europe.org](mailto:rdm-toolkit@elixir-europe.org). Do not hide the email address behind a word or phrase like "contact us". * **Etc.** should be avoided. Try using ‘for example’ or ‘such as’ or ‘including’ at the start of a listing. If etc. is used, put a comma before it if it is in a list, like "A, B, etc.". * **Gender:** avoid using gender-specific words like "he" or "she". * **Headings:** - * Only the first word is capitalised, unless other words are proper nouns. - * Headings must be hierarchical. They must go down in order (level one, level two, level three), and not skip a level. It is fine to skip levels when moving back up e.g. you can skip from level four to level two. + * Only the first word is capitalised unless other words are proper nouns. + * Headings must be hierarchical. They must go down in order (level one, level two, level three) and not skip a level. It is fine to skip levels when moving back up, e.g. you can skip from level four to level two. * **-ise/-ize:** use the "-ise" form. * **Life cycle:** two separate words. - * **Links:** make the link text say where the link goes e.g. "the Contribute page", not "click here". Avoid using the url as the link text. + * **Links:** make the link text say where the link goes, e.g. "the Contribute page", not "click here". Avoid using the url as the link text. * **Lists:** * _A list of short items_: introduce with a colon, start each bullet point with a capital and don't use punctuation at the end of each bullet point: * Item 1 * Item 2 - * _A list of longer items following an incomplete introductory sentence (e.g. a sentence ending in a colon)_: each item ends with a semi colon and the final item ends with a full stop. Do not capitalise the first letter of each item e.g. This is the first part of a sentence that includes: + * _A list of longer items following an incomplete introductory sentence (e.g. a sentence ending in a colon)_: each item ends with a semi-colon and the final item ends with a full stop. Do not capitalise the first letter of each item, e.g. This is the first part of a sentence that includes: * a longer item 1; * a longer item 2; * a longer item 3. - * _A list following a complete sentence (with a full stop)_: each item ends with a full stop and each point begins with a capital letter e.g. This a complete sentence. + * _A list following a complete sentence (with a full stop)_: each item ends with a full stop, and each point begins with a capital letter, e.g. This a complete sentence. * This is item 1 of the list. * This is item 2 of the list. * This is item 3 of the list. * **Numbers:** spell the numbers one to ten out. After that, write the numbers (11, 12, 13, etc.). - * **Quotations:** use double quotes for quotations, and single quotes for quotes within quotes. + * **Quotations:** use double quotes for quotations and single quotes for quotes within quotes. + * **References:** + * add your citations as bibtex to the `_bibliography/references.bib` file + * add `{% cite reference_key %}` to the text where you are citing the reference + * add `## Bibliography` `{% bibliography --cited %}` to show a bibliography section with cited refrences on a page. * **That/which:** use "that" when you are defining something and "which" when you are adding extra information about it e.g.: * "The cat that was on the table suddenly got up" is telling us which cat it was. It is important to the meaning of the sentence because you are not talking about any cat, just the cat on the table. - * "The cat, which was sitting on the table, suddenly got up" is giving us extra information about the cat. The information is not necessary to understand the sentence. You can remove the clause and the sentence will still be clear. Clauses starting with "which" usually begin with a comma. + * "The cat, which was sitting on the table, suddenly got up" is giving us extra information about the cat. The information is not necessary to understand the sentence. You can remove the clause, and the sentence will still be clear. Clauses starting with "which" usually begin with a comma. * **Titles (the "title" in the front matter of pages):** only the first word, proper nouns and acronyms are capitalised. * **Tool assembly:** there are multiple tools in **one** assembly. The plural is "tool assemblies". * **Training:** training is an uncountable noun and cannot have a plural. You can write "training courses" and "training materials" but not "trainings". @@ -96,9 +100,9 @@ not be part of the information provided by the contributors. | | #73757d | Gray | Gray text, Fourth level heading (h4) | | | #f3f1f2 | Light gray | Box backgrounds | * **Fonts:** Exo 2 is used for headings and main branding font, Open Sans for body text. - * **Icons:** the icons used in the data life cycle diagram come from the [Noun Project](https://thenounproject.com/ELIXIRCommunications/kit/rdmkit/). We have a Pro license and so the right to publish them without attribution. Other icons on this site are either desgined by Xènia Pérez Sitjà or come from [Font Awesome](https://fontawesome.com/). + * **Icons:** the icons used in the data life cycle diagram come from the [Noun Project](https://thenounproject.com/ELIXIRCommunications/kit/rdmkit/). We have a Pro license and the right to publish them without attribution. Other icons on this site are either desgined by Xènia Pérez Sitjà or come from [Font Awesome](https://fontawesome.com/). * **Templates:** keep the structure of the pages consistent by using the site templates (see the [contribute page](how_to_contribute)). - * **Illustrations:** use the colours listed above. The icons we use for illustrations come from the [Noun Project](https://thenounproject.com/ELIXIRCommunications/kit/rdmkit/). Please use these icons in any illustrations. If you need extra icons, or any help with illustrations, [open a new issue](https://github.com/elixir-europe/rdmkit/issues) on GitHub or email [rdm-toolkit@elixir-europe.org](mailto:rdm-toolkit@elixir-europe.org). + * **Illustrations:** use the colours listed above. The icons we use for illustrations come from the [Noun Project](https://thenounproject.com/ELIXIRCommunications/kit/rdmkit/). Please use these icons in any illustrations. If you need extra icons or any help with illustrations, [open a new issue](https://github.com/elixir-europe/rdmkit/issues) on GitHub or email [rdm-toolkit@elixir-europe.org](mailto:rdm-toolkit@elixir-europe.org). * **Images:** * Do not use images to display text. * Include an 'alt' attribute in images. @@ -107,12 +111,12 @@ not be part of the information provided by the contributors. * **Markdown file names:** * Do not contain spaces or special characters like &, %, #, (, ), è, é, ê, ë, ... - * Are unique among the website. + * Are unique across the website. * Are lowercase, except for acronyms. * **Tags for tools, resources and pages:** * Do not contain special characters like &, %, #, (, ), è, é, ê, ë, ... * Are lowercase, except for acronyms. - * Are short if possible, but distinguishable from existing tags. + * Are short if possible but distinguishable from existing tags. * Can contain spaces. * **Keywords:** * Are lowercase. diff --git a/pages/contribute/tool_resource_update.md b/pages/contribute/tool_resource_update.md index 87c88ea07..8397d2dc4 100644 --- a/pages/contribute/tool_resource_update.md +++ b/pages/contribute/tool_resource_update.md @@ -7,11 +7,11 @@ summary: How to add a tool or resource to RDMkit The tools or resources you will find on pages are a selected set from a [bigger list](all_tools_and_resources). This selection is based on the appearance of a tool or resource in the content of the page. -Since the `Data life cycle` pages are not listing tools, no tools table will be present in these pages. Tool and resource mentions are allowed in the following sections: `Your domain`, `Your role`, `Your tasks` and `Tool assembly`. +Since the `Data life cycle` pages do not list tools, no tools table will be present on these pages. Tool and resource mentions are allowed in the following sections: `Your domain`, `Your role`, `Your tasks` and `Tool assembly`. The [all_tools_and_resources](all_tools_and_resources) list is based on the [yaml file](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml) in the `_data` directory of the RDMkit repository. Tools and resources can be manually linked to [FAIRsharing.org](https://fairsharing.org/), [Bio.tools](https://bio.tools) and [TeSS](https://tess.elixir-europe.org/), but every week we also run a fully automatic check that links tools and resources with the corresponding registries. A GitHub Bot will generate a Pull Request (PR) with the new links added to the main data file of the website. -{% include callout.html type="important" content="The link with FAIRsharing,TeSS and Bio.tools is automatically done using GitHub actions and is weekly updated. If no FAIRsharing ID, Bio.tools ID or TeSS Query is available for a source, but there is yet one automatically given (faulty), you can overwrite the automatic linking by adding 'NA' as registry." %} +{% include callout.html type="important" content="The link with FAIRsharing,TeSS and Bio.tools is automatically done using GitHub actions and is updated weekly. If no FAIRsharing ID, Bio.tools ID or TeSS query is available for a source, but there is yet one automatically given (faulty), you can overwrite the automatic linking by adding 'NA' as a registry." %} ## The main yaml file @@ -20,7 +20,7 @@ Each tool or resource mentioned in the text has metadata stored in the [main yam - **name**: the name of the tool or resource - **url**: URL to the main page of the tool or resource, make sure to let the URL start with `https://` - **description**: A short description of the tool or resource. Try to not use the characters `"` or `'` -- **registry**: 3 registries are supported: [Bio.tools](https://bio.tools), [FAIRsharing.org](https://fairsharing.org/) and [TeSS](https://tess.elixir-europe.org/). The keywords you can use respectively are: `biotools`, `fairsharing`, `fairsharing-coll` and `tess`, specifying the id or query with a colon. FAIRsharing collections have an ID that follows the pattern `bsg-s000XXX`. List registries under the `registry` attribute as `key: value pairs`. If no FAIRsharing ID, Bio.tools ID or TeSS Query is available for a source, you can overwrite the automatic linking by adding 'NA' as registry. +- **registry**: 3 registries are supported: [Bio.tools](https://bio.tools), [FAIRsharing.org](https://fairsharing.org/) and [TeSS](https://tess.elixir-europe.org/). The keywords you can use respectively are: `biotools`, `fairsharing`, `fairsharing-coll` and `tess`, specifying the id or query with a colon. FAIRsharing collections have an ID that follows the pattern `bsg-s000XXX`. List registries under the `registry` attribute as `key: value pairs`. If no FAIRsharing ID, Bio.tools ID or TeSS query is available for a source, you can overwrite the automatic linking by adding 'NA' as a registry. Example: @@ -43,11 +43,11 @@ Tools and resources specifically mentioned in the text of the pages should be pr 1. Make sure the tool you want to add is not yet already described in the [yaml file](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml). If so, go to step 3, if not, go follow the next step. -1. Click on the pencil icon seen on GitHub of the [main yaml file](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml) as described in our GitHub Guide. Add your tool or resource at the bottom of the file following the structure described in the [The main yaml file section of this page](#the-main-yaml-file). Make sure the indentation follows the one of the previous listed items. Copy the content of the yaml file and paste in in an online yaml validator in case of doubt. +1. Click on the pencil icon seen on GitHub of the [main yaml file](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml) as described in our GitHub Guide. Add your tool or resource at the bottom of the file following the structure described in the [The main yaml file section of this page](#the-main-yaml-file). Make sure the indentation follows one of the previously listed items. In case of doubt, copy the content of the yaml file and paste it into an online yaml validator to check the format. 1. Copy the `tool_id` of the tool or resource -1. Add the right context on RDMkit for the tool by mentioning it somewhere in the text using following syntax: +1. Add the right context on RDMkit for the tool by mentioning it somewhere in the text using the following syntax: ``` {% raw %} diff --git a/pages/contribute/working_with_git.md b/pages/contribute/working_with_git.md index d9b48c83e..7b611a239 100644 --- a/pages/contribute/working_with_git.md +++ b/pages/contribute/working_with_git.md @@ -2,6 +2,13 @@ title: Working with git --- +This guide tells you how to request and edit a page using Git and GitHub. + +Prerequisites: +* Basic knowledge of Markdown. All you need to know is in our [markdown cheat sheet](markdown_cheat_sheet) +* Technical knowledge about Git. +* A GitHub account. If you do not have one, [create a free GitHub account](https://github.com/join) before you start. + ## Forking - branching - changing - pushing - PR diff --git a/pages/your_role/data_steward.md b/pages/your_role/data_steward.md index a64941b15..d05cc6e70 100644 --- a/pages/your_role/data_steward.md +++ b/pages/your_role/data_steward.md @@ -1,7 +1,7 @@ --- title: Data Steward description: Data management guidance for data stewards. -contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xenia Perez-Sitja, Nazeefa Fatima, Gregoire Rossier, Federico Bianchini, Erik Hjerde, Minna Ahokas, Priit Adler, Alexander Botzki, Robert Andrews, Celia van Gelder, Graham Hughes, Marko Vidak, Pedro Fernandes, Pinar Alper, Victoria Dominguez D. Angel, Wolmar Nyberg Åkerström, Alexia Cardona] +contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xènia Pérez Sitjà, Nazeefa Fatima, Gregoire Rossier, Federico Bianchini, Erik Hjerde, Minna Ahokas, Priit Adler, Alexander Botzki, Robert Andrews, Celia van Gelder, Graham Hughes, Marko Vidak, Pedro Fernandes, Pinar Alper, Victoria Dominguez D. Angel, Wolmar Nyberg Åkerström, Alexia Cardona] page_id: data_steward redirect_from: [data_steward_infrastructure, data_steward_policy, data_steward_research] --- diff --git a/pages/your_role/principal_investigator.md b/pages/your_role/principal_investigator.md index 3c61085b4..3e31a779b 100644 --- a/pages/your_role/principal_investigator.md +++ b/pages/your_role/principal_investigator.md @@ -1,7 +1,7 @@ --- title: Principal Investigator (PI) description: Data management guidance for Principal Investigator (PI). -contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xenia Perez-Sitja, Nazeefa Fatima, Gregoire Rossier] +contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xènia Pérez Sitjà, Nazeefa Fatima, Gregoire Rossier] page_id: principal_investigator --- diff --git a/pages/your_role/research_software_engineer.md b/pages/your_role/research_software_engineer.md index df174dd6f..0820ad509 100644 --- a/pages/your_role/research_software_engineer.md +++ b/pages/your_role/research_software_engineer.md @@ -1,7 +1,7 @@ --- title: Research Software Engineer (RSE) description: Data management guidance for Research Software Engineers (RSEs). -contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xenia Perez-Sitja, Nazeefa Fatima, Gregoire Rossier, Federico Bianchini, Erik Hjerde, Minna Ahokas, Priit Adler, Alexander Botzki, Robert Andrews, Celia van Gelder, Graham Hughes, Marko Vidak, Pedro Fernandes, Pinar Alper, Victoria Dominguez D. Angel, Wolmar Nyberg Åkerström, Alexia Cardona] +contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xènia Pérez Sitjà, Nazeefa Fatima, Gregoire Rossier, Federico Bianchini, Erik Hjerde, Minna Ahokas, Priit Adler, Alexander Botzki, Robert Andrews, Celia van Gelder, Graham Hughes, Marko Vidak, Pedro Fernandes, Pinar Alper, Victoria Dominguez D. Angel, Wolmar Nyberg Åkerström, Alexia Cardona] page_id: research_software_engineer --- diff --git a/pages/your_role/researcher.md b/pages/your_role/researcher.md index 4fa87084f..7fc49b34e 100644 --- a/pages/your_role/researcher.md +++ b/pages/your_role/researcher.md @@ -1,7 +1,7 @@ --- title: Researcher description: Data management guidance for researchers, including how to make your data FAIR. -contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xenia Perez-Sitja, Nazeefa Fatima, Gregoire Rossier, Federico Bianchini, Erik Hjerde, Siiri Fuchs, Minna Ahokas, Priit Adler, Alexander Botzki, Robert Andrews, Celia van Gelder, Graham Hughes, Marko Vidak, Pedro Fernandes, Pinar Alper, Victoria Dominguez D. Angel, Wolmar Nyberg Åkerström, Alexia Cardona, Munazah Andrabi] +contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xènia Pérez Sitjà, Nazeefa Fatima, Gregoire Rossier, Federico Bianchini, Erik Hjerde, Siiri Fuchs, Minna Ahokas, Priit Adler, Alexander Botzki, Robert Andrews, Celia van Gelder, Graham Hughes, Marko Vidak, Pedro Fernandes, Pinar Alper, Victoria Dominguez D. Angel, Wolmar Nyberg Åkerström, Alexia Cardona, Munazah Andrabi] page_id: researcher --- diff --git a/pages/your_role/trainer.md b/pages/your_role/trainer.md index b55942d6d..e4dbb1f90 100644 --- a/pages/your_role/trainer.md +++ b/pages/your_role/trainer.md @@ -1,7 +1,7 @@ --- title: Trainer description: Data management guidance for trainers. -contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xenia Perez-Sitja, Nazeefa Fatima, Gregoire Rossier] +contributors: [Mijke Jetten, Martin Cook, Siiri Fuchs, Ulrike Wittig, Daniel Wibberg, Helena Schnitzer, Xènia Pérez Sitjà, Nazeefa Fatima, Gregoire Rossier] page_id: trainer ---