Contribution Plan for the IFRC GIS Training Platform#

Introduction#

Thank you for your interest in contributing to the IFRC GIS Training Resource Center. This page outline the contribution process and guideline for collaborating with the GIS Training Resource Center. It provides details for contributions and related best practices. Whether you’re looking to add new content, contribute to existing material, or collaborate on enhancing the platform overall as a partner, this guide will help to understand the necessary steps.

Collaborations#

Content#

Collaborators are encourages to propose new topics or content relevant to the GIS Training Resource Center. These topics should align with the training objectives for Anticipatory Action (AA), Information Management and focus on basic GIS operations. If you have a topic in mind, please send a brief introduction and key points to gis-training-platform@heigit.org to initiate collaboration.

To help us understand and evaluate your proposal, kindly consider the following three guiding questions:

  1. What level of GIS expertise is required for the proposed content?

  2. What is the main learning objective or added value of the proposed content?

  3. Will you be adding the content to the training platform yourself (in markdown), or would you require support?

We will review and assess each idea on a case-by-case basis.

Interested in becoming a Partner or Supporter of the Training Resource Platform?#

The GIS Training Working Group behind the IFRC GIS Training Resource Center was established by the British, German, and Netherlands Red Cross Societies, with technical support from the Heidelberg Institute for Geoinformation Technology (HeiGIT).

In addition to content contributions, this consortium welcomes new partners from the Red Cross and Red Crescent Movement. We also encourage contributions in the form on in-kind or financial support to help further develop and drive continuous improvement of the platform.

Content Contribution Guidelines#

Your contribution#

  • Markdown MyST and Jupyter Book: In addition to CommonMark Markdown, Jupyter Book also supports a more fully-featured version of Markdown called MyST Markdown. This is a superset of CommonMark that includes syntactic pieces that are useful for publishing computational narratives. For more information about MyST Markdown, see MyST Markdown overview.

  • Changes on the Dev-Branch:

    • All changes must be pushed to the dev branch. These changes will be reviewed by HeiGIT and/or RC before a pull request is merged.

    • Currently, only HeiGIT or RC are authorized to create pull requests and contributors can request reviews from HeiGIT and/or RC via GitHub.

  • New Content:

    • If you have ideas for new content (either as new sections in existing modules or new standalone modules), send us an email or submit an issue in github using the appropriate tags. A proposal may also include a markdown page or suggested structure.

    • New content proposals will undergo review, and contributors are encouraged to actively engage with reviewers via GitHub issues. For deeper discussions about content or collaborations, HeiGIT/RC are happy to schedule video calls.

  • External Data Submission:

    • If you need to send data or other materials, you can email them to gis-training-platform@heigit.org to be uploaded to the Nexus Data Repository.

Licences#

  • Copyright and Data Sources: Always provide clear citations for any external material, including articles, books, and web content. For articles and books, include the full citation with DOI. For webpages, include the source URL (external links must be maintained)

  • All content within the platform will be published under the CC 4.0 BY-NC-SA license

Ideal Structure for New Content#

The structure of new modules/chapters should ideally include:

  1. Theory: Introduction to key concepts.

  2. Practical Examples: Demonstrate how to apply concepts in Anticipatory Action, Information Management, and QGIS.

  3. Exercises: Hands-on practice with follow-along exercises.

  4. Synthesis: A more complex exercise or example that synthesizes the module content

  5. Self-Assessment Questions: To test comprehension of the module’s main concepts

Types of Content#

  • Theory: Explanation of concepts.

  • Real World Examples: Include practical examples that are relevant to the GIS field (preferably related to IM, AA, or humanitarian work in general).

  • Exercises: Follow-along or self-guided exercises to reinforce learning.

  • Discussion Questions: Promote interaction and connection to real-world scenarios.

  • Wiki: Brief articles that provide explanations or instructions related to the platform.

  • Figures: Pictures or figures to illustrate theoretical concepts, real world examples or show screenshots

  • Videos: The platform uses short videos without commentary to show how to perform certain steps (e.g., edit the attribute table, import layers, or set the symbology of a layer)

Note

Keep in mind that there are many detailed GIS resources as well as official documentation. Explain the necessary theory for trainees to perform the tasks. You can also refer to external resources.

Exercise Guidelines#

  • Instructions: Provide step-by-step instructions.

  • Facilitator Notes: Include notes for facilitators on how to guide the exercise.

  • Data: Always provide a link to the dataset(s) used in the exercise. Ensure the dataset is cleaned of personal data and errors unless data cleaning is part of the exercise.

Note

Contributors are encouraged to upload videos for step-by-step guides where useful.

File naming and Formatting Guidelines#

Follow these guidelines for naming files and structuring directories:

  • Naming: Choose descriptive names. Ensure that exercises are numbered correctly (e.g. module_#_ex#_title). The exercise number should be the next available number

  • Folder Structure: Ensure that exercise data follows the correct folder structure and is zipped correctly (avoid excessive folder nesting as this can lead to problems when unzipping)

  • Language and QGIS Version: Always include the QGIS version and language in the file names.

  • Pictures: All pictures and figures have to be stored in the folder /fig/.

    • General common pictures just have to have a sort and informative title.

      • Picture name example: HeiGIT_logo_compact.svg

    • In the case of a screenshot of QGIS or another program, additional rules apply. First, the abbreviation of the used language has to be included (e.g. en). Second, the QGIS version (e.g. 3.28).

      • Screenshots name example: en_3.29_clip_tool.png

    • In instances of pictures of the OSM or satellite imagery, one has to include the year and place.

      • Picture of maps or satellite imagery example: OSM_Heidelberg_2023.png

Follow these guidelines when creating and formatting content:

  • Spelling: Use British English spelling.

  • Headings:

    • # Title for the main titles of markdown pages

    • ## Title for sections

    • ### Title for subsections

    • Avoid headings deeper than H3 (### Title). Use bold, underlining or put it into cards to achieve a similar effect.

  • Links:

    • In Markdown, you can embed links into text by using [text/name](link)

  • Figures and Images:

    • Images and videos are saved to the /fig/-folder.

    • Use the figure directive for images:

      :::{figure} /fig/example.png
---
name: example_figure
width: 750 px
align: center/left/right
---
Descriptive Caption including source of the image
:::

    • name must indicate a unique descriptive name. You can refer to figure in text by using:

      {numref}`name`

      • This does not work in pages that are not included in the TOC.yml-file

    • width specifies the pixel width. The maximum amount of pixels for width is 750 px. Alternatively, you can use height. Be careful to set high values as this will distort the image once it reaches the 750 px width cap.

    • align specifies where the image should be rendered on the markdown page. E.g., align: left can be used to align the image to the left part of the page and leave space for text on the right.

    • The caption should describe what is seen on the figure in the context of the section. The image sources must be specified as precisely as possible.

    • It is possible to embed icons into the text by using ![](/fig/FILENAME). Make sure the icon height does not exceed 30 pixels.

  • Admonitions:

    • Use admonitions such as note, caution, tip, tldr for additional notes such as

    :::{admonition} TITLE
:class: tip, caution, note, tldr, note
CONTENT
:::

  • Dropdowns: For optional content (e.g. videos or supplementary information), use dropdowns:

    :::{dropdowns} TITLE
CONTENT
:::

  • Cards: Use the card directives to highlight content in a “card”:

    :::{card}
HEADER
^^^
CONTENT
:::

  • Grids: To create several columns to display content or images side by side, you can create grids:

    ::::{grid} 2

:::{card}

:::

:::{card}

:::

::::

  • Margins: Sometimes, it can be useful to put hints or additional information into the margin to the right. This can be achieved with the following directive:

    ::::{margin}
CONTENT (can include other directives)
::::

Nesting directives

It is possible to nest directives such as figures inside of cards or admonitions. Simply use more colons around directives that enclose other such as:


::::{card}
HEADER
^^^
CONTENT

:::{figure} /fig/figure.png
---
name:
width:
align:
---
CAPTION
:::

::::

  • Embedding Videos: Videos need to be embedded using HTML-code:

    <video width="100%" controls src="https://github.com/GIScience/gis-training-resource-center/raw/main/fig/qgis_change_project_CRS.mp4"></video>

    • copy the code and enter the name of the video file you want to embed.

  • Text formatting standards:

    • When describing a process, use numbers. For example:

      1. Right-click on "ML1_IPC_Index" layer -> `Attribute Table`-> click on  [`Field Calculator`](https://giscience.github.io/gis-training-resource-center/content/Wiki/en_qgis_table_functions_wiki.html#calculate-field) ![](/fig/mActionCalculateField.png) to open the field calculator
2. Check `Create new field`
3. `Output field name`: Name the new column “Trigger_activation”
4. `Result field type`: Text (string)

    • All clickable surface has to be written as code snippets e.g. Attribute Table

    • If a special icon is used in QGIS, place it next to the code snippets e.g Field Calculator .

    • If an option needs to be selected, write the click surface name in code snippet and the option as normal text e.g. Result field type: Text (string)

    • If something like a file name has to be named in a certain way use quotation marks e.g. Output field name: Name the new column “Trigger_activation”

    • Where it makes sense add the link to the relevant wiki video when the participants should use a tool or a functionality that is not in detail described in your current step-by-step guide either by linking the tool name e.g. drag and drop or by using something like (Wiki basemap)