Merge pull request #10 from elixir-europe-training/glossary

Introduce a glossary to index and disambiguate acronyms

Gemfile

@@ -2,4 +2,5 @@ source "https://rubygems.org"
 
 group :jekyll_plugins do
     gem "github-pages"
-  end
+    gem "jekyll-glossary_tooltip", "~> 1.5"
+end

_config.yml

@@ -75,4 +75,5 @@ plugins:
   - jemoji
   - jekyll-sitemap
   - jekyll-github-metadata
+  - jekyll-glossary_tooltip
   - webrick

_data/glossary.yml

@@ -0,0 +1,11 @@
+- term: SPLASH
+  definition: Backronym for SPLASH (to be defined)
+  url: https://elixir-europe-training.github.io/ELIXIR-Training-SPLASH/about
+- term: TODO
+  definition: Work to be done
+- term: PR
+  definition: Pull Request
+  url: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
+- term: URL
+  definition: Uniform Resource Locator
+  url: https://en.wikipedia.org/wiki/URL

pages/contribute/editorial_board_guide.md

@@ -23,27 +23,27 @@ These markdown files are divided over subdirectories (your_role, your_tools, you
 
 ### GitHub checks
 
-With each PR or merge to the master, some checks are done using GitHub actions. One of them checks wether the website builds correctly. The other checks for changes in the tool/resource Excel table. When each of them fails, the PR will not be able to be merged. Click on the red dot/failed check to understand better what caused the fail. 
+With each {% glossary PR %} or merge to the master, some checks are done using GitHub actions. One of them checks wether the website builds correctly. The other checks for changes in the tool/resource Excel table. When each of them fails, the {% glossary PR %} will not be able to be merged. Click on the red dot/failed check to understand better what caused the fail. 
 
 ## Label, discuss and assign issues
 
   * Check open issues regularly or enable notifications by clicking the "WATCH" icon in the top-right side of the [GitHub repository](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/issues).
   * Assign labels to issues.
   * Discuss who is going to be responsible for each issue with other editors and reviewers (via issue comments or other communication channels).
   * Assign at least one editor/reviewer to the issue, who will discuss the possible content with the contributor.
-  * When a Pull Request (PR) or a draft PR related to an issue is created, link the PR to the issue.
+  * When a Pull Request ({% glossary PR %}) or a draft {% glossary PR %} related to an issue is created, link the {% glossary PR %} to the issue.
 
 More information about these topics can be found in the GitHub documentation:
-- [commenting on PRs](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)
+- [commenting on {% glossary PR %}s](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)
 - [start a review](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request)
 
 ## Review pull requests
 
-If contributors make a pull request to make changes, by default the editors that are responsible for files that will be changed by the PR will be assigned and notified. All PR should be assigned to one of the editors. Before merging a PR, pages' tags, and tools and resources' tags should be checked and assigned according to the established tagging system. The editor who provides the last approval to a PR should also merge it.
+If contributors make a pull request to make changes, by default the editors that are responsible for files that will be changed by the {% glossary PR %} will be assigned and notified. All {% glossary PR %} should be assigned to one of the editors. Before merging a {% glossary PR %}, pages' tags, and tools and resources' tags should be checked and assigned according to the established tagging system. The editor who provides the last approval to a {% glossary PR %} should also merge it.
 
 ## Link a pull request to an issue
 
-When you make a pull request resolving an issue, it is possible to link this pull request to that specific issue. This can be easily done by writing in the conversation of the PR: `closes #number_of_issue`, or `fixes #number_of_issue` or even `resolves #number_of_issue`. This is definitely applicable when authors first open an issue announcing a change or requesting a new page, followed up by the pull request. 
+When you make a pull request resolving an issue, it is possible to link this pull request to that specific issue. This can be easily done by writing in the conversation of the {% glossary PR %}: `closes #number_of_issue`, or `fixes #number_of_issue` or even `resolves #number_of_issue`. This is definitely applicable when authors first open an issue announcing a change or requesting a new page, followed up by the pull request. 
 For more information about this topic please visit the [GitHub documentation page](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue).
 
 ## Create a new page
@@ -93,12 +93,12 @@ By default your page will not be linked in the sidebar on the website, or on the
 
 Make sure all pages are accessible from the navigation sidebar. Please, avoid generating sub-pages that are not directly accessible from the navigation sidebar.
 
-This website supports multiple sidebars, the one in the main sections of the website is for example different from the one in the contribute section. Both of them are defined by `.yaml` files in the *_data/sidebars* directory. Changing these yaml file will immediately impact the sidebars and the frontpage of the website. The sidebar supports multiple levels and each level in the hierarchy can contain a URL to a page within this website or an external URL.
+This website supports multiple sidebars, the one in the main sections of the website is for example different from the one in the contribute section. Both of them are defined by `.yaml` files in the *_data/sidebars* directory. Changing these yaml file will immediately impact the sidebars and the frontpage of the website. The sidebar supports multiple levels and each level in the hierarchy can contain a {% glossary URL %} to a page within this website or an external {% glossary URL %}.
 
 The attributes that define the structure are:
 - `title`: This is the text that will show up in the sidebar.
-- `url`: The URL to the internal page you want to link to. This is mostly in the form of: */markdown_file_name.html*.
-- `external_url`: Use this instead of URL if you want to link to an external page.
+- `url`: The {% glossary URL %} to the internal page you want to link to. This is mostly in the form of: */markdown_file_name.html*.
+- `external_url`: Use this instead of {% glossary URL %} if you want to link to an external page.
 - `subitems`: to define a sublevel.
 
 ```yaml
@@ -164,7 +164,7 @@ The logos can be added to the [/images/institutions](https://github.com/elixir-e
 {% include callout.html type="important" content="Upload vector images (.svg filetype) of the institute logo for better quality, scaleability and file size, if possible." %}
 
 
-TODO:
+{% glossary TODO %}:
 
 ## Related pages
 

pages/contribute/editors_checklist.md

@@ -1,12 +1,12 @@
 ---
 title: Editors checklist
-summary: Checklist for editors before approving and merging a pull request (PR).
+summary: Checklist for editors before approving and merging a pull request ({% glossary PR %}).
 ---
 
-## Before approving and merging a pull request (PR), the editors must check that
+## Before approving and merging a pull request ({% glossary PR %}), the editors must check that
 1. The page layout in preview looks correct.
-2. The new page is linked in the appropriate [sidebar](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/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-training/ELIXIR-Training-SPLASH/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-training/ELIXIR-Training-SPLASH/blob/master/_data/CONTRIBUTORS.yaml).
+2. The new page is linked in the appropriate [sidebar](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/tree/master/_data/sidebars) menu, in the same branch of the {% glossary PR %}.
+3. The contributors' names are listed in the [CONTRIBUTORS file](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/blob/master/_data/CONTRIBUTORS.yaml), in the same branch of the {% glossary PR %}. Advice to have at least one  contributor per page having its contact information in this  [CONTRIBUTORS file](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/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.
    * unique `page_id` ([List of page IDs](website_overview))
    * `contributors`
@@ -21,4 +21,4 @@ summary: Checklist for editors before approving and merging a pull request (PR).
 6. There are no [copyright](copyright) issues related to the content of the page.
 7. The contributors implemented the requested changes.
 8. The contributors are thanked for their effort and informed about the publication of their content.
-9. The PR is linked to related issues and can be merged in main branch with no conflicts.
+9. The {% glossary PR %} is linked to related issues and can be merged in main branch with no conflicts.

pages/contribute/github_way.md

@@ -28,7 +28,7 @@ This guide tells you how you can easily request and edit a page on this website.
 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:
+1. You are now redirected to the Pull Request ({% glossary 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" %}

pages/contribute/preview_changes.md

@@ -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 ({% glossary PR %}) with you 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 {% glossary PR %} to the main repository.
 
 {% include image.html file="create_pr_from_fork.png" alt="Create new PR from fork." %}
 

pages/contribute/style_guide.md

@@ -12,7 +12,7 @@ In general, we follow the European Commission's [Web Writing Style Guide](https:
   * Use the words your readers would use. Think of the terms they would use when searching for their problem, and use those terms.
 
 ## Text
-  * **Acronyms:** spell them out the first time.
+  * **Acronyms:** use the [glossary file](_data/glossary.yml) and [these instructions](https://github.com/erikw/jekyll-glossary_tooltip#usage) to spell out acronyms in an accessible way.
   * **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).)
@@ -52,7 +52,7 @@ In general, we follow the European Commission's [Web Writing Style Guide](https:
   * **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".
 
-TODO: define color scheme
+{% glossary TODO %}: define color scheme
 
 ## Graphic design
   * **White space:** make sure there is plenty of space so that the main elements stand out and the text does not appear overwhelming.

pages/contribute/tool_resource_update.md

@@ -9,7 +9,7 @@ The tools or resources you will find on pages are a filtered set from a [bigger
 
 Since the `Data life cycle` pages are not listing tools, we do not allow page_id from this section in the tool table. page_id allowed in the tool table are page_id from the following sections: `Your domain`, `Your role`, `Your tasks` and `Tool assembly`. The page_id can be found in the [List of page IDs](website_overview). 
 
-The [all_tools_and_resources](all_tools_and_resources) list is based on the [csv file](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/blob/master/_data/main_tool_and_resource_list.csv) in the `_data` directory of the current 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 (a yaml file).
+The [all_tools_and_resources](all_tools_and_resources) list is based on the [csv file](https://github.com/elixir-europe-training/ELIXIR-Training-SPLASH/blob/master/_data/main_tool_and_resource_list.csv) in the `_data` directory of the current 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 ({% glossary PR %}) with the new links added to the main data file of the website (a yaml file).
 
 {% include callout.html type="important" content="The link with FAIRsharing,TeSS and Bio.tools is automatically done using GitHub actions and is weekly updated. These automatic links are not seen in the table. The search query to one of these registries for a tool or resource can be overwritten in the registry column of the main csv tool table. 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." %}
 
@@ -19,12 +19,12 @@ The main table is based on [this google spreadsheet]().
 
 The table consists of 5 columns:
 - **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://`
+- **url**: {% glossary URL %} to the main page of the tool or resource, make sure to let the {% glossary 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 multiple registries using a comma `, ` between the keywords to separate the key:value pairs. The values that are given in the table will always overrule the automatic links. 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.
 - **related_pages**: This is used to tag the tools so it is listed on the correct page. We only allow page_id that are linked to a page. To find out what the page_id of a page is, please check its metadata attribute `page_id` at the top of the markdown file or the [List of page IDs](website_overview) page. Since the Data life cycle pages are not listing tools, we do not allow these page_id in the tool table. page_id allowed in the tool table are page_id from the following sections: `Your domain`, `Your role`, `Your tasks` and `Tool assembly`. List multiple page_id by using a comma `, ` between them.
 
-TODO: adapt examples
+{% glossary TODO %}: adapt examples
 
 | name     | url                             | description                                                                               | registry                                    | related_pages                                             |
 |----------|----------------------------------|-------------------------------------------------------------------------------------------|---------------------------------------------|--------------------------------------------------|
@@ -49,4 +49,4 @@ The editors will do the work on Git for you. All you need to do is:
 - Done! The editors will update the "tool and resource list" in GitHub regularly. In case your change is urgent, ping an editor in an issue or pull request.
 
 ## Let the editor and GitHub bot do the rest
-If the PR of the editor containing the changes to the .csv table is merged, a PR will be opened by github-actions. Please check that the changes this PR proposes to the yaml file are in line with what you want to have changed.
+If the {% glossary PR %} of the editor containing the changes to the .csv table is merged, a {% glossary PR %} will be opened by github-actions. Please check that the changes this {% glossary PR %} proposes to the yaml file are in line with what you want to have changed.

pages/contribute/working_with_git.md

@@ -3,7 +3,7 @@ title: Working with git
 ---
 
 
-## Forking - branching - changing - pushing - PR
+## Forking - branching - changing - pushing - {% glossary PR %}
 
 This is a general workflow in how to work on your own fork (copy) of the current repo and request changes through a pull request:
 NOTE: if you already did these steps in the past, start from the `git fetch upstream` command.