Improve the concept of "resources" in the RDMkit (#1532)

* start improving resources

* betetr box

* new variations

* describing what a tool or resource is in the RDMkit

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update tool_resource_update.md

* Update tool_resource_update.md (#1590)

updates on documentation of FAIRsharing IDs

* Update tool_resource_update.md

* update icon

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

* Update pages/contribute/tool_resource_update.md

Co-authored-by: Federico Bianchini <[email protected]>

---------

Co-authored-by: Federico Bianchini <[email protected]>

_sass/_custom_classes.scss

@@ -244,7 +244,7 @@ i.fa-solid.fa-magnifying-glass {
 // Tool snippet
 
 i.fa-solid.fa-wrench {
-    background: url("../img/section-icons/tools.svg") center no-repeat;
+    background: url("../img/section-icons/info2.svg") center no-repeat;
     &:before {
         content: "";
     }

pages/contribute/tool_resource_update.md

@@ -1,26 +1,41 @@
 ---
 title: Add new tool or resource
-summary: How to add a tool or resource to RDMkit
 ---
 
 ## Way of working
 
-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.
+You will find a "Tools and resources on this page" section at the bottom of most pages. The entries of this section are a subset of the [All tools and resources](all_tools_and_resources) table. The appearance of a tool or resource in this subset is solely determined by the fact that it is mentioned in the content of that page using the syntax described below.
 
-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) table is described in a central YAML file, [tool_and_resource_list.yml](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml), in the `_data` directory. 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/). We also run a fully automatic weekly check that links tools and resources with the corresponding registries. A GitHub Bot will open a Pull Request (PR) when new links are found.
 
-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="Possible links between a tool or resource and registries such as FAIRsharing, TeSS, or bio.tools are automatically identified using GitHub Actions on a weekly basis. If the automatically proposed link is not relevant, and there is no other FAIRsharing ID, bio.tools ID, or TeSS query available for the source, you can overwrite the automatic linking by adding `NA` as the value of a registry field." %}
 
-{% 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
+## When can you add a new tool or resource
 
-Each tool or resource mentioned in the text has metadata stored in the [main yaml file](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml). The metadata block for each tool consists of 5 attributes:
+Tools and resources mentioned in the text of the pages should be included in the main table. However, not everything qualifies as a tool or resource in the context of RDMkit. Specifically, the following are **not** considered tools or resources:  
+- **Publications**: Articles, white papers, or other academic literature. See our [style guide](https://rdmkit.elixir-europe.org/style_guide#bibliography) on adding publications to a bibliography.
+- **Policies**: Guidelines, mandates, or institutional frameworks.  
+- **Webpages of groups or consortia**: Informational pages or organisational websites without a dedicated tool or service.
+
+Additionally, it is important to note that we do not distinguish between tools and resources; these terms are used interchangeably throughout RDMkit.
+
+Tool and resource mentions are allowed only in the following sections:  
+- **Your domain**  
+- **Your role**  
+- **Your tasks**  
+- **Tool assembly**  
+
+If your contribution aligns with these criteria, follow the steps outlined below to add your entries to the main YAML file.
+
+## The main YAML file
+
+Each tool or resource mentioned in the text has metadata stored in the [main YAML file](https://github.com/elixir-europe/rdmkit/blob/master/_data/tool_and_resource_list.yml). The metadata block for each tool consists of 5 attributes:
 - **id**: The ID of a tool, in kebab-case, lowercase with hyphens.
 - **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 a 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. For FAIRsharing, copy the alphanumeric characters after "FAIRsharing." in the DOI. FAIRsharing collections are not associated with a DOI but use a four-digit ID well-visible on the page. 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:
 
@@ -33,17 +48,14 @@ Example:
     small data
   registry:
     tess: GitHub
+    fairsharing: c55d5e
 ```
 
+## Linking the tool or resource in the text with the main YAML file
 
-## What tool or resource can be added to the table
-Tools and resources specifically mentioned in the text of the pages should be present in the main table. 
-
-## Making changes
-
-1. Make sure the tool you want to add is not 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, follow the next step.
+1. Make sure the tool you want to add is not already listed 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, 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 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. 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
 
@@ -55,7 +67,7 @@ Tools and resources specifically mentioned in the text of the pages should be pr
   {% endraw %}
   ```
 
-  {% include callout.html type="important" content="Don't forget to add the `\"` double quotes around the tool_id and make sure to use the exact tool_id as described in the yaml file." %}
+  {% include callout.html type="important" content="Don't forget to add the `\"` double quotes around the tool_id and make sure to use the exact tool_id as described in the YAML file." %}
 
   Example: