Contribution

Guidelines for contributing, including adding new content or editing existing materials.

We highly recommend reading Ten simple rules for making training materials FAIR before creating a new training material and following the FAIR (Findable, Accessible, Interoperable, Reusable) principles for training materials.

Preview the website
Add a new tutorial
- Edit the tutorial
- Format the content
  - Boxes
  - Images
Create a new learning pathway

Preview the website

There are two options to run the website locally and preview your training materials before pushing them.

Option 1: Using Ruby and Bundler

You need Ruby and Bundler installed. Then run:

# Install required gems
bundle install

# Start the Jekyll server
bundle exec jekyll serve --trace --livereload

Open http://127.0.0.1:4000/training/ (Server address) in your browser to view the website.

Option 2: Using Docker

Build and run the containerized version:

# Build the Docker image
docker build . -t dekcd

# Run the container
docker run -it -p 4000:4000 dekcd

Then open http://127.0.0.1:4000/training/ in your browser.

Add a new tutorial

To add a new tutorial, create a new folder in _tutorials folder and place the tutorial content in a single tutorial.md within the tutorial directory (or a subdirectory if you have multiple versions of the same tutorial).

When creating a new tutorial, add the folder name (slug) to the _data/tutorial_groups.yml file. This links your tutorial to an existing tutorial group. If your tutorial belongs to a new category that does not yet exist, create a new group entry in _data/tutorial_groups.yml with a clear description of the group.

Then, commit the changes to the new branch and submit a pull request.

Optionally you can also go to issues and “create an issue” with the format add new tutorial that describes what you are adding.

Edit the tutorial

The tutorial.md should have the following structure:

---
layout: tutorial_hands_on

title: Title of the tutorial
description: Description of the tutorial
slug: slugified title
time_estimation: HM
questions:
  - Which questions are addressed by the tutorial?
objectives:
  - The learning objectives of the tutorial
key_points:
- The take-home messages
- They will appear at the end of the tutorial
version: tutorial version
life_cycle: tutorial lifecycle
contributions:
  authorship:
  - author 1
  - author 2
  editing: 
  funding: 
---

## Section title

Enter your tutorial content here.

The tutorial requires the metadata to be included at the top:

keep the layout as tutorial_hands_on by default.
title: the title of the tutorial will appear on the Collection of Tutorials page.
time_estimation: the estimated time needed to complete the hands-on tutorial. It must match the following regular expression pattern: /^(?:([0-9]+)[Hh])?(?:([0-9]+)[Mm])?(?:([0-9.]+)[Ss])?$/
questions: a list of questions that will be addressed in the tutorial.
objectives: a list of learning objectives for the tutorial.
key_points: a list of take-home messages that will appear at the end of the tutorial.
contributions: a list of tutorial contributors broken down into broad categories to help contributors identify how they contributed to a specific tutorial. Examples include authorship, editing, funding, testing, infrastructure, and translation.

In the funding section, list the name of the organization that supported the training material. Ensure that the organization’s name matches an entry in _data/contributions.yml. If your organization is not listed, please add its name to the file and place the organization’s logo in /assets/img/.

Development status of tutorials

The development status of tutorials follows a framework similar to that of the Carpentries. Training materials are classified into four categories: alpha, beta, stable, and deprecated.

Alpha: the tutorial is in the early stages of development. Its content may be incomplete, untested, and subject to significant changes. This status typically applies until a complete first draft is available.

Beta: the tutorial is in the testing phase, being reviewed and taught by other instructors. Feedback from pilot workshops is actively incorporated, and further revisions are likely.

Stable: the tutorial is considered complete, reliable, and well-maintained. Only minor updates are expected, with no major changes anticipated.

Deprecated: the tutorial is no longer maintained and may be removed in the future.

The following information can also be included in the tutorial metadata:

zenodo_link: link to the input data for the tutorial on Zenodo.
follow_up_training: a list of resources that the reader of the material could follow at the end of the tutorial.

For additional information that could be included in the tutorial metadata, please refer to the GTN tutorial.

If you have any data or images that you would like to add to the tutorial, please place them in the tutorial directory.

Format the content

Boxes

To improve the learning experience in our tutorial, we define some boxes to highlight content. Below is an example of the “Task box with solutions”:

> ## Questions
> 1. Question 1
> 2. Question 2
>  
> > ## Answers
> > 1. Answer 1
> > 2. Answer 2
> > 
> {: .solution}
>
{: .question}

which will look like this:

Questions

Question 1

Question 2

Answers

Answer 1

Answer 2

There are several boxes that you can use to format the content of your training material: {: .overview}, {: .key_points}, {: .tip}, {: .warning}, {: .comment}, {: .hands_on}, {: .question}, {: .solution}, {: .details}, {: .feedback}, {: .code-in}, and {: .code-out}.

Tasks

Create each box and see how it looks.

Create one with a nested box.

Examples

Tasks

List of tasks

…

Details

Here put some text…

Tip

Here put some useful information…

Comment

Here put some comments…

Code In

ls -lh

import pandas as pd

Code Out
# code output

Questions

Question 1

Question 2

Answers

Answer 1

Answer 2

Images

To insert an inline image in a way that works both locally and when deployed, use:

![figure-title](/training/tutorials/%3Ctutorial-folder%3E/%3Cimage-folder%3E/%3Cimage%3E){: .responsive-img }

![figure-title]() this is standard Markdown image syntax. The text inside the brackets (figure-title) becomes the alt text, which improves accessibility and is displayed if the image fails to load.
/training/path/to/image the relative_url ensures that the correct baseurl defined in _config.yml is automatically prepended. This prevents broken links when the site is hosted in a subdirectory.
{: .responsive-img } CSS class constrains the image to the content width, prevents overflow, and scales the image proportionally on smaller screens.

Additional resources

If you need an additional materials to learn how to format the tutorial content, i.e. to wrap parts of the text in the special block quotes, please refer to the Software Carpenters’ Formatting episode.

Please also refer to the Markdown Cheatsheet to learn more how to use Markdown.

Create a new learning pathway

To add a new learning pathway, create <pathway_title>.md file in _pathways folder. The <pathway_title>.md should have the following structure:

---
layout: pathway
title: Title of the Learning Pathway
description: Description of the Learning Pathway
tags: []
pathway:
  - section: "Module 1: Title of the Module
    description: Description of the Module
    tutorials:
      - name: tutorial name
        version: main

  - section: "Module 1: ..."
    description: ...
    tutorials:
      - name: ...
        version: ...
editorial_board:
  - name: ...
    orcid: ...
---

Keep the layout: pathway as default. Commit changes to the new branch and pull a request.

Contribution

Table of Contents

Preview the website

Add a new tutorial

Edit the tutorial

Development status of tutorials

Format the content

Boxes

Questions

Answers

Tasks

Examples

Tasks

Details

Tip

Comment

Code In

Code Out

Questions

Answers

Images

Additional resources

Create a new learning pathway