update swate template contribution guide

src/docs/guides/swate_template-contribution.md

@@ -1,21 +1,22 @@
 ---
 layout: docs
 title: Swate Templates Contribution Guide
-date: 2023-08-14
+date: 2024-03-22
 author: 
 - name: Dominik Brilhaus
   github: https://github.com/brilator
   orcid: https://orcid.org/0000-0001-9021-3197
 - name: Kevin Frey
   github: https://github.com/Freymaurer
   orcid: https://orcid.org/0000-0002-8510-6810
+- name: Stella Eggels
 add toc: true
 add sidebar: _sidebars\mainSidebar.md
 ---
 
 ## About this guide
 
-This tutorial guides you how to create and share Swate metadata templates.
+This tutorial guides you how to create Swate metadata templates with [Swate-alpha](https://swate-alpha.nfdi4plants.org/).
 
 <a href="./index.html">
   <span class="badge-category">User</span><span class="badge-selected" id="badge-datasteward">Data Steward</span>
@@ -38,7 +39,7 @@ This tutorial guides you how to create and share Swate metadata templates.
 
 Before contributing Swate templates you ideally have
 
-- :ballot_box_with_check: Access to an up-to-date [installation](./../SwateManual/Docs01-Installing-Swate.html) of **Swate Core** and **Swate Experts**  
+- :ballot_box_with_check: Access to [Swate-alpha](https://swate-alpha.nfdi4plants.org/)
 - :ballot_box_with_check: Some routine with Swate (e.g. from the Swate manual and quickstarts)
   - you know how to create an [Annotation Table](./../SwateManual/Docs02-Annotation-Table.html)
   - you know how to [add building blocks](./../SwateManual/Docs03-Building-Blocks.html) to your annotation table
@@ -61,149 +62,91 @@ Before contributing Swate templates you ideally have
 
 ## Creating a new Swate template
 
-### Create a new Annotation Table in a fresh Excel workbook
+### Create or open a Swate template
 
-<style scoped>
-.columns {
-    display: grid;
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-    /* grid-template-columns: 700px 400px; */
-    gap: 20px;
-}
-figure {
-  position: relative;
-  width: 350px;
-}
-
-figcaption {
-  position: absolute;
-  top: 0;
-  right: 0;
-  /* width: 40px; */
-  padding-left: 60px;
-  font-size: 20px;
-  writing-mode: vertical-rl;
-}
-</style>
+Open [Swate-alpha](https://swate-alpha.nfdi4plants.org/). To create a new template click "New File" and select "Template". If you want to edit an existing template, click "Import" and select the respective file. 
+![img1](./../img/Swate-alpha-newtemplate.png) 
 
-<div class="columns">
-<div class="columns-left">
+### Add Template Metadata
 
-- Open a new Excel workbook `<template>.xlsx`
-- Create an [Annotation Table](./Docs02-Annotation-Table.html)
-- Save the Excel file in a suitable folder within your local clone of the Swate templates repository
-  - :bulb: check the subfolder README.md`s  
-  - :construction: naming convention for files and directories is work in progress
+Once you open a new template, you will see a "Metadata" sheet. Here you will enter a name for the template as well as further information describing the template. You can find explanations of the necessary information in the table below. 
 
-- [Add building blocks](./Docs03-Building-Blocks.html) to your template's Annotation Table
 
-</div>
-<div class="columns-right">
+#### Template Metadata Explanation
 
-<figure>
-  <img src="./../img/swate-templates_repo_local.png">
-  <figcaption>Local clone of Swate templates repository (April 19, 2023)</figcaption>
-</figure>
+Key | Definition | Tip :bulb:
+------- | ------- | -------
+**Identifier** |   | Do not change this field. It maps your template to a database entry :warning:
+**Name** |  This is the first info Swate users see about your template  |  Try using a short, descriptive and human readable name. Capitalize the first letter of the first word.
+**Description** |  Here you can describe your template. |  Users interested in your template can read this in Swate, but not search by it.
+**Organisation** |  The name of an organisation or community you create this template for. This facilitates searching for relevant templates in a specific organisation or community. |  Templates with the organisation "DataPLANT" are listed as `curated` in the Swate template database. All other templates are listed as `community`.
+**Version** |  The version of the template following the [SemVer](https://semver.org/) convention.  |  For a new template use `1.0.0`. Raise the version number when updating an existing template.
+**Tags** |  You can add any number of tags here. These tags are the basis to search for your template. | If possible add them as ontology terms with source ontology (TSR) and unique identifier (TAN). If similar tags already exist, consider reusing the existing ones.
+**Endpoint Repositories** |  If your template complies with the requirements of an endpoint repository, you can add the respective repository here. | You may want to add them as ontology terms with source (TSR) and identifier (TAN).
+**Authors** |  Add your name/alias here with as much information as you like.
 
-</div>
-</div>
 
-### Recommendations for template design
 
-- Keep the template as concise as possible
-- Finding suitable building blocks is not always straight-forward
-- 👀 If you miss a term or ontology, please follow the [DPBO contribution guide](https://github.com/nfdi4plants/nfdi4plants_ontology) to let us know
-- If you add a template to address a missing method, try to add building blocks that cover experimental procedures (as Parameters) and features of the sample (as Characteristics) that the experimenter would do when working on an experiment of that type
-- If you add a template with a specific endpoint repository (ER) in mind, you may want to add building blocks that match the required fields of this ER
-- Avoid using the building block type `Factor` in templates. Any given characteristic or parameter in one study or assay can become a factor in another study or assay depending on the experimental context or scientific question. E.g. in one study all samples originate from the same `species` (-> Characteristic) whereas in another study multiple `species` where assayed (-> Factor). 
-
-### Add Template Metadata
+#### Template Metadata Example
 
 <style scoped>
 .columns {
     display: grid;
     grid-template-columns: repeat(2, minmax(0, 1fr));
-    gap: 20px;
+    gap: 50px;
 }
 
 </style>
 
-- Open the "Template Metadata" tab in **Swate Experts** <img height=10px src='https://raw.githubusercontent.com/nfdi4plants/Branding/master/icons/Swate/Excel/Experts/swate_e_40x40.png'/>
-- Click "Create Metadata"
-- A new worksheet will open called "SwateMetadataSheet"
+Here is an example for filled out template metadata and how it helps in Swate's template search.
 
 <div class="columns">
 
 <div class="columns-left">
-<img src="./../img/swateExperts-tab-templateMetadata.png" style="height: 300px">
+<img src="./../img/Swate-alpha-metadata-example.png">
 </div>
 
 <div class="columns-right">
-<img src="./../img/swate-templates-metadata.png" style="height: 300px">
+<img src="./../img/Swate-alpha-templateselection.png">
 </div>
 
 </div>
 
 
-> :warning: Make sure to never change any of the fields in the first column. These "key" fields must exist to create a functional template. Always only change the "value" fields (second and following columns).
-
-### Template Metadata Explanation
+### Add building blocks
 
-Key | Definition | Tip :bulb:
-------- | ------- | -------
-**Id** |   | Do not change this field. It maps your template to a database entry :warning:
-**Name** |  This is the first info Swate users see about your template  |  Try using a short, descriptive and human readable name. (Think YouTube video title)
-**Version** |  The version of the template following the [SemVer](https://semver.org/) convention.  |  For a new template use `1.0.0`. Raise the version number when updating an existing template
-**Description** |  Here you can describe your template |  Users interested in your template can read this in Swate, but not search by it
-**Organisation** |  The name of an organisation or community you create this template for. This facilitates searching for relevant templates in a specific organisation or community. |  Templates with the organisation "DataPLANT" are listed as `curated` in the Swate template database. All other templates are listed as `community`.
-**Table** |  This value **must match** the name of the annotation table you want to use as a template |  To find the name click on any field in your annotation table, then open the `Table Design` (on macOS: `Table`) tab. Copy the name to the "Table" value field <img src="./../img/Swate-templates_find_table_name.jpg" style="height: 150px"  />
-**ER list** |  You can add any number of endpoint repositories to which your template complies here | You may want to add them as ontology terms with unique identifier and source
-**TAGS list** |  You can add any number of tags here. These tags are the basis to search for your template | You may want to add them as ontology terms with unique identifier and source
-**AUTHORS list** |  Add your name/alias here with as much information as you like.
-
-
-
-### Template Metadata Example
-
-<style scoped>
-.columns {
-    display: grid;
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-    gap: 50px;
-}
+To add the building blocks of your actual template, you need to switch from the "Metadata" sheet to the "New Table" sheet on the bottom left. Using the "Add Building Block" button, you can add your desired building blocks with or without a unit.
+![img1](./../img/Swate-alpha-buildingblock.png) 
 
-</style>
+#### Recommendations for template design
 
-Here is an example for filled out template metadata and how it helps in Swate's template search.
-
-<div class="columns">
-
-<div class="columns-left">
-<img src="./../img/Swate-templates_example_metadata.jpg">
-</div>
+- Keep the template as concise as possible
+- 👀 If you miss a term or ontology, please follow the [DPBO contribution guide](https://github.com/nfdi4plants/nfdi4plants_ontology) to let us know
+- If you add a template to address a missing method, try to add building blocks that cover experimental procedures (as Parameters) and features of the sample (as Characteristics) that the experimenter would use when working on an experiment of that type
+- Try to think about in which order the experimenter in the lab will do their work. Try to match this chronological order from left to right. The normal order of the columns is: **Input** -> (all the Parameters and Characteristics in between in chronological order) -> **Output** -or- **Raw Data File** -or- **Derived Data File**. This step is optional and only meant to increase readability.
+- If you would like to save any background information on your template, that would help others reconstruct the creation of the template, you can save it in the [Swate-templates GitHub repository](https://github.com/nfdi4plants/Swate-templates). For this, please create a folder with the name of your template in the "Background information" folder. 
+- Avoid using the building block type `Factor` in templates. Any given characteristic or parameter in one study or assay can become a factor in another study or assay depending on the experimental context or scientific question. E.g. in one study all samples originate from the same `species` (-> Characteristic) whereas in another study multiple `species` where assayed (-> Factor). 
 
-<div class="columns-right">
-<img src="./../img/swate-tab-templates_example.png">
-</div>
+#### Recommendations for adding endpoint repository templates
+- When creating a template to comply with repository requirements, please follow the following naming pattern: "Repository" - "Assay", e.g. MetaboLights - MS measurement
+- The endpoint repository tag should be added ONLY in the "Endpoint repository" category in the metadata sheet
+- By default repository templates should contain only mandatory information. In this case, please add "mandatory" as a tag.
+- Optional or recommended information can be added with an extension template that contains ONLY the optional/recommended information. In this case, please add "-extension" to the template name. 
+- If applicable, templates should be split into different assays.
+- Templates should be checked for validity of requirements every ~ 6 months.
 
-</div>
+### Save your template
 
+Save your template by clicking on the disc symbol in the top right corner. This will download an xlsx-file. Please adjust the name of the file to correspond to the name of the template, but use underscores instead of spaces.
+Save the Excel file in a suitable folder within your local clone of the Swate templates repository.
 
 ### Your template is ready for upload :tada:
 
 - Well done! You created a new template.
 - You can now submit your template via the git workflow described above.
 - Once your pull request is merged, you will receive an Email from "Swobup Commit Report"
 
-## Recommended best practices
-
-- Try to think about in which order the experimenter in the lab will do their work. Try to match this chronological order from left to right. The normal order of the columns is: **Source Name** -> (all the Parameters and Characteristics in between in chronological order) -> **Sample Name** -or- **Raw Data File** -or- **Derived Data File**. This step is optional and only meant to increase readability.
-- Below the header you can add exemplary terms as in this example:  
-![image](https://user-images.githubusercontent.com/47781170/146252236-0dd11621-76e9-4d28-b5fe-b495362a1cc5.png)  
-These examples help as additional information for other Data Stewards and are not transferred into the Swate template database.
-- Use ontology terms for **ER list** and **TAGS list**.
-- Add protocol type and any [minimal information standards](https://en.wikipedia.org/wiki/Minimum_information_standard) your template complies with to the **TAGS list**.
 
 ## Known pitfalls with Swate Templates
 
-- Opening and saving a Swate template .xlsx file with a program other than Microsoft Excel (e.g. LibreOffice, python script, R script) often destroys the template (backend). Please, avoid to upload this file into the GitHub repository, even if the annotation table itself looks intact and can be worked on with the Swate plugin
+- Opening and saving a Swate template .xlsx file with a program other than Microsoft Excel (e.g. LibreOffice, python script, R script) often destroys the template (backend). Please, avoid to upload this file into the GitHub repository.