|
|
|
# How To for Publishers
|
|
|
|
|
|
|
|
The Sharing Platform is an open platform to provide and exchange material for teaching programming to students from universities and secondary schools. The material can comprise text exercises, programming exercises, lecture material (e.g. slides), or other useful topics (as e.g. links to other valuable tools or sources outside the sharing platform).
|
|
|
|
|
|
|
|
Beyond single entries you can also publish a collections of materials in order to provide e.g. complete courses. See the section "3.Decide on the structure of your contribution" for a reference to more detailed information.
|
|
|
|
|
|
|
|
You are welcome to contribute. In the following we want to guide you through the process of material sharing. Please note that the sharing platform is still evolving. If you have any proposals how to improve the sharing and finding of contents, do not hesitate to open an new issue in the [sharing plattform project](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/).
|
|
|
|
|
|
|
|
In the following we try to guide you through the basic process of publishing on the sharing plattform.
|
|
|
|
|
|
|
|
## 1\. Decide on the format of the material you want to share
|
|
|
|
|
|
|
|
You share your material via a gitlab repository. So there are little technical restrictions on the structure and contents of your contribution.
|
|
|
|
|
|
|
|
The recommended format highly depends on the context how your material was historically developed, and how you expect it to be used by your colleagues.
|
|
|
|
|
|
|
|
For **text exercises** we recommend the presentation with the following priorities
|
|
|
|
|
|
|
|
1. **LaTeX** or **MarkDown** format
|
|
|
|
2. **Microsoft Office** (or **Open Office**) format
|
|
|
|
3. **Plain Text**
|
|
|
|
4. _less recommended_: pdf format, because it does not really support easy reuse of content by others
|
|
|
|
|
|
|
|
Additionally for images:
|
|
|
|
|
|
|
|
1. Some editable format that can be reused and adapted by other users: e.g. [PlantUML ](https://plantuml.com/en/)(as used in GitLab), SVG, ... that can be easily embedded in the rendered (HTML) text.
|
|
|
|
2. Commonly used image formats: jpeg, png, gif
|
|
|
|
- consider also in this case to also provide the image sources that can be edited
|
|
|
|
|
|
|
|
For **programming exercises** we recommend, that the problem statement should follow the recommendations of a text exercise as above. The format of additional information, as e.g. programming templates provided to the students, a sample solution or specific automated tests may be language specific. We recommend a specific file/folder structure for these exercises (see below). Artemis already provides some export functionality in the recommended format (see [here](en/documentation/SharingFromArtemis)).
|
|
|
|
|
|
|
|
For **lecture material** we recommend the following formatting priorities
|
|
|
|
|
|
|
|
1. **SliTeX** together with the relevant additional image and formatting files
|
|
|
|
2. **Microsoft Office** (or **Open Office**) formats
|
|
|
|
3. **Plain Text**
|
|
|
|
4. Online Formats: Google Slide, etc.
|
|
|
|
5. _less recommended_: pdf format, because it does not really support reuse of content
|
|
|
|
|
|
|
|
For **other material** decide what is best suited for potential users. Most likely a README.md file may be appropriate to give a basic documentation and to link to other stuff.
|
|
|
|
|
|
|
|
## 2\. Decide on the location of your contribution
|
|
|
|
|
|
|
|
The backbone of the sharing platform is a gitlab instance at https://sharing-codeability.uibk.ac.at/. You should locate your contribution in an appropriate sub folder below your institution (e.g. https://sharing-codeability.uibk.ac.at/sharing/johannes-kepler-university-linz/java/Einfuehrung1/...).
|
|
|
|
|
|
|
|
Alternatively you can also use your personal gitlab namespace for publications. As soon as you project contains a valid metadata file, it will be registered (and published according to the gitlab visibility settings of your project).
|
|
|
|
|
|
|
|
## 3\. Decide on the structure of your contribution
|
|
|
|
|
|
|
|
The smallest publication unit on the sharing platform is a single exercise.
|
|
|
|
|
|
|
|
You can combine various exercises into a collection, e.g. a complete course, or another thematic combiniation of exercises. Elements in the collections can either be other gitlab projects on the sharing plattform, or simply subdirectories of the collection project. You find more information in the [metadata description](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/MetaData-Documentation) in the section "collections".
|
|
|
|
|
|
|
|
In order to provide future services we would propose the following structure:
|
|
|
|
|
|
|
|
1. a metadata.yaml is _mandatory_ (alternatively a metadata.yml or a metadata.json is also appropriate), See further information below.
|
|
|
|
2. a README.md is _recommended_. It should give a basic overview to the contents of your contribution beyond the description in the metadata.
|
|
|
|
3. for complex content of exercises we _recommend_ the following folder structure:
|
|
|
|
- an **exercise** folder: should contain all basic files, a student needs to start solving the exercise
|
|
|
|
- a **solution** folder: should contain the sample solution of the exercise (see section 4 if the solution should not be published)
|
|
|
|
- a **test** folder: should contain the infrastructure to test a submitted exercise for its validity
|
|
|
|
4. any further content (e.g. images), that may be needed to re-use the exercise.
|
|
|
|
|
|
|
|
## 4\. Decide on the visibility of your contribution
|
|
|
|
|
|
|
|
For sharing, we recommend to make your project **public** in gitlab.
|
|
|
|
|
|
|
|
If you are reluctant to make your exercise public, you can make your gitlab project private and open it only for a certain group of members. The Sharing Platform will reflect this restrictions for publication.
|
|
|
|
|
|
|
|
Currently the default is, that your project is shared under the **sharing** group, which comprises all codeability partners.
|
|
|
|
|
|
|
|
If you decide to make your exercise public, please note that (due to Gitlab permission handling) also every parent group must be public.
|
|
|
|
|
|
|
|
For private projects there is an explicit mechanism to make only parts of the project publicly visible: you can use the special attribute `publicVisibility`, e.g.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
publicVisibility:
|
|
|
|
except:
|
|
|
|
- "solution"
|
|
|
|
```
|
|
|
|
|
|
|
|
Which makes the project findable by any user. However the download-zip does not contain the folder `solution`.
|
|
|
|
|
|
|
|
You can find more information on the help page on [permissons](en/publishers/permissions).
|
|
|
|
|
|
|
|
## 5\. Provide helpful metadata
|
|
|
|
|
|
|
|
The metadata.yaml is _mandatory_ (alternatively a metadata.yml or a metadata.json is also appropriate). It contains information about your exercise, necessary to discover it by an interested user.
|
|
|
|
|
|
|
|
A full description of the metadata format can be found [here](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/MetaData-Documentation).
|
|
|
|
|
|
|
|
Some fields in the metadata are required and some are optional. We encourage you to have a look at what is available and to include the data relevant for the content you upload.
|
|
|
|
|
|
|
|
The following is an example showing the specification of a C programming exercise.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
metadataVersion: "0.4"
|
|
|
|
learningResourceType: programming exercise
|
|
|
|
title: C Artemis Tutorial Compile
|
|
|
|
description: Find a compilation error in a given program. A semicolon is missing in the provided file. Students should fix this issue by looking at the compiler feedback provided by Artemis.
|
|
|
|
license: CC-SA-BY 4.0
|
|
|
|
keyword:
|
|
|
|
- Artemis
|
|
|
|
- tutorial
|
|
|
|
format:
|
|
|
|
- md
|
|
|
|
- artemis
|
|
|
|
structure: atomic
|
|
|
|
language:
|
|
|
|
- de
|
|
|
|
programmingLanguage:
|
|
|
|
- C
|
|
|
|
creator:
|
|
|
|
- name: Priller Simon
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
- name: Kaltenbrunner Lukas
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
publisher:
|
|
|
|
- name: Priller Simon
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
- name: Kaltenbrunner Lukas
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
difficulty: simple
|
|
|
|
educationalLevel:
|
|
|
|
- beginners
|
|
|
|
image: "https://en.wikipedia.org/wiki/C_(programming_language)#/media/File:The_C_Programming_Language_logo.svg"
|
|
|
|
status: final
|
|
|
|
isBasedOn:
|
|
|
|
- "https://artemis.codeability.uibk.ac.at/course-management/51/programming-exercises/652"
|
|
|
|
identifier: at.ac.uibk.eidp.s21.s00e03
|
|
|
|
subject:
|
|
|
|
- "Universität Innsbruck-Einführung in die Programmierung"
|
|
|
|
```
|
|
|
|
|
|
|
|
Currently the metadata format for version 0.4 and 0.5 is supported.
|
|
|
|
|
|
|
|
Please refer to the [documentation of metadata](https://sharing-codeability.uibk.ac.at/development/sharing/codeability-sharing-platform/-/wikis/Metadata/Metadata-Version-0.4-Documentation) for a full up-to-date reference of the available fields.
|
|
|
|
|
|
|
|
## 6\. Maintain your contents and Peer Reviewing
|
|
|
|
|
|
|
|
Every time you push a new commit to the master branch, the project is checked for the presence of the metadata file. If it is not present, or its content is not valid, you will get an error e-mail, pointing out the problems.
|
|
|
|
|
|
|
|
As long as there are errors in you meta data, the last valid version is reused (or the project is not indexed at all, if no previous valid version exists). So please correct these errors.
|
|
|
|
|
|
|
|
Please take care for your contributions over time. Currently you have to check on your own, whether the material is still valid and accurate (e.g. with progressing versions of a programming language).
|
|
|
|
|
|
|
|
# How To for Publishers
|
|
|
|
|
|
|
|
The Sharing Platform is an open platform to provide and exchange material for teaching programming to students from universities and secondary schools. The material can comprise text exercises, programming exercises, lecture material (e.g. slides), or other useful topics (as e.g. links to other valuable tools or sources outside the sharing platform).
|
|
|
|
|
|
|
|
Beyond single entries you can also publish a collections of materials in order to provide e.g. complete courses. See the section "3.Decide on the structure of your contribution" for a reference to more detailed information.
|
|
|
|
|
|
|
|
You are welcome to contribute. In the following we want to guide you through the process of material sharing. Please note that the sharing platform is still evolving. If you have any proposals how to improve the sharing and finding of contents, do not hesitate to open an new issue in the [sharing plattform project](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/).
|
|
|
|
|
|
|
|
In the following we try to guide you through the basic process of publishing on the sharing plattform.
|
|
|
|
|
|
|
|
## 1\. Decide on the format of the material you want to share
|
|
|
|
|
|
|
|
You share your material via a gitlab repository. So there are little technical restrictions on the structure and contents of your contribution.
|
|
|
|
|
|
|
|
The recommended format highly depends on the context how your material was historically developed, and how you expect it to be used by your colleagues.
|
|
|
|
|
|
|
|
For **text exercises** we recommend the presentation with the following priorities
|
|
|
|
|
|
|
|
1. **LaTeX** or **MarkDown** format
|
|
|
|
2. **Microsoft Office** (or **Open Office**) format
|
|
|
|
3. **Plain Text**
|
|
|
|
4. _less recommended_: pdf format, because it does not really support easy reuse of content by others
|
|
|
|
|
|
|
|
Additionally for images:
|
|
|
|
|
|
|
|
1. Some editable format that can be reused and adapted by other users: e.g. [PlantUML ](https://plantuml.com/en/)(as used in GitLab), SVG, ... that can be easily embedded in the rendered (HTML) text.
|
|
|
|
2. Commonly used image formats: jpeg, png, gif
|
|
|
|
- consider also in this case to also provide the image sources that can be edited
|
|
|
|
|
|
|
|
For **programming exercises** we recommend, that the problem statement should follow the recommendations of a text exercise as above. The format of additional information, as e.g. programming templates provided to the students, a sample solution or specific automated tests may be language specific. We recommend a specific file/folder structure for these exercises (see below). Artemis already provides some export functionality in the recommended format (see [here](en/documentation/SharingFromArtemis)).
|
|
|
|
|
|
|
|
For **lecture material** we recommend the following formatting priorities
|
|
|
|
|
|
|
|
1. **SliTeX** together with the relevant additional image and formatting files
|
|
|
|
2. **Microsoft Office** (or **Open Office**) formats
|
|
|
|
3. **Plain Text**
|
|
|
|
4. Online Formats: Google Slide, etc.
|
|
|
|
5. _less recommended_: pdf format, because it does not really support reuse of content
|
|
|
|
|
|
|
|
For **other material** decide what is best suited for potential users. Most likely a README.md file may be appropriate to give a basic documentation and to link to other stuff.
|
|
|
|
|
|
|
|
## 2\. Decide on the location of your contribution
|
|
|
|
|
|
|
|
The backbone of the sharing platform is a gitlab instance at https://sharing-codeability.uibk.ac.at/. You should locate your contribution in an appropriate sub folder below your institution (e.g. https://sharing-codeability.uibk.ac.at/sharing/johannes-kepler-university-linz/java/Einfuehrung1/...).
|
|
|
|
|
|
|
|
Alternatively you can also use your personal gitlab namespace for publications. As soon as you project contains a valid metadata file, it will be registered (and published according to the gitlab visibility settings of your project).
|
|
|
|
|
|
|
|
## 3\. Decide on the structure of your contribution
|
|
|
|
|
|
|
|
The smallest publication unit on the sharing platform is a single exercise.
|
|
|
|
|
|
|
|
You can combine various exercises into a collection, e.g. a complete course, or another thematic combiniation of exercises. Elements in the collections can either be other gitlab projects on the sharing plattform, or simply subdirectories of the collection project. You find more information in the [metadata description](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/MetaData-Documentation) in the section "collections".
|
|
|
|
|
|
|
|
In order to provide future services we would propose the following structure:
|
|
|
|
|
|
|
|
1. a metadata.yaml is _mandatory_ (alternatively a metadata.yml or a metadata.json is also appropriate), See further information below.
|
|
|
|
2. a README.md is _recommended_. It should give a basic overview to the contents of your contribution beyond the description in the metadata.
|
|
|
|
3. for complex content of exercises we _recommend_ the following folder structure:
|
|
|
|
- an **exercise** folder: should contain all basic files, a student needs to start solving the exercise
|
|
|
|
- a **solution** folder: should contain the sample solution of the exercise (see section 4 if the solution should not be published)
|
|
|
|
- a **test** folder: should contain the infrastructure to test a submitted exercise for its validity
|
|
|
|
4. any further content (e.g. images), that may be needed to re-use the exercise.
|
|
|
|
|
|
|
|
## 4\. Decide on the visibility of your contribution
|
|
|
|
|
|
|
|
For sharing, we recommend to make your project **public** in gitlab.
|
|
|
|
|
|
|
|
If you are reluctant to make your exercise public, you can make your gitlab project private and open it only for a certain group of members. The Sharing Platform will reflect this restrictions for publication.
|
|
|
|
|
|
|
|
Currently the default is, that your project is shared under the **sharing** group, which comprises all codeability partners.
|
|
|
|
|
|
|
|
If you decide to make your exercise public, please note that (due to Gitlab permission handling) also every parent group must be public.
|
|
|
|
|
|
|
|
For private projects there is an explicit mechanism to make only parts of the project publicly visible: you can use the special attribute `publicVisibility`, e.g.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
publicVisibility:
|
|
|
|
except:
|
|
|
|
- "solution"
|
|
|
|
```
|
|
|
|
|
|
|
|
Which makes the project findable by any user. However the download-zip does not contain the folder `solution`.
|
|
|
|
|
|
|
|
You can find more information on the help page on [permissons](en/publishers/permissions).
|
|
|
|
|
|
|
|
## 5\. Provide helpful metadata
|
|
|
|
|
|
|
|
The metadata.yaml is _mandatory_ (alternatively a metadata.yml or a metadata.json is also appropriate). It contains information about your exercise, necessary to discover it by an interested user.
|
|
|
|
|
|
|
|
A full description of the metadata format can be found [here](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/MetaData-Documentation).
|
|
|
|
|
|
|
|
Some fields in the metadata are required and some are optional. We encourage you to have a look at what is available and to include the data relevant for the content you upload.
|
|
|
|
|
|
|
|
The following is an example showing the specification of a C programming exercise.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
metadataVersion: "0.4"
|
|
|
|
learningResourceType: programming exercise
|
|
|
|
title: C Artemis Tutorial Compile
|
|
|
|
description: Find a compilation error in a given program. A semicolon is missing in the provided file. Students should fix this issue by looking at the compiler feedback provided by Artemis.
|
|
|
|
license: CC-SA-BY 4.0
|
|
|
|
keyword:
|
|
|
|
- Artemis
|
|
|
|
- tutorial
|
|
|
|
format:
|
|
|
|
- md
|
|
|
|
- artemis
|
|
|
|
structure: atomic
|
|
|
|
language:
|
|
|
|
- de
|
|
|
|
programmingLanguage:
|
|
|
|
- C
|
|
|
|
creator:
|
|
|
|
- name: Priller Simon
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
- name: Kaltenbrunner Lukas
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
publisher:
|
|
|
|
- name: Priller Simon
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
- name: Kaltenbrunner Lukas
|
|
|
|
affiliation: "Universität Innsbruck"
|
|
|
|
email: email@nospam.ac.at
|
|
|
|
difficulty: simple
|
|
|
|
educationalLevel:
|
|
|
|
- beginners
|
|
|
|
image: "https://en.wikipedia.org/wiki/C_(programming_language)#/media/File:The_C_Programming_Language_logo.svg"
|
|
|
|
status: final
|
|
|
|
isBasedOn:
|
|
|
|
- "https://artemis.codeability.uibk.ac.at/course-management/51/programming-exercises/652"
|
|
|
|
identifier: at.ac.uibk.eidp.s21.s00e03
|
|
|
|
subject:
|
|
|
|
- "Universität Innsbruck-Einführung in die Programmierung"
|
|
|
|
```
|
|
|
|
|
|
|
|
Currently the metadata format for version 0.4 and 0.5 is supported.
|
|
|
|
|
|
|
|
Please refer to the [documentation of metadata](https://sharing-codeability.uibk.ac.at/development/sharing/codeability-sharing-platform/-/wikis/Metadata/Metadata-Version-0.5-Documentation) for a full up-to-date reference of the available fields.
|
|
|
|
|
|
|
|
## 6\. Maintain your contents and Peer Reviewing
|
|
|
|
|
|
|
|
Every time you push a new commit to the master branch, the project is checked for the presence of the metadata file. If it is not present, or its content is not valid, you will get an error e-mail, pointing out the problems.
|
|
|
|
|
|
|
|
As long as there are errors in you meta data, the last valid version is reused (or the project is not indexed at all, if no previous valid version exists). So please correct these errors.
|
|
|
|
|
|
|
|
Please take care for your contributions over time. Currently you have to check on your own, whether the material is still valid and accurate (e.g. with progressing versions of a programming language).
|
|
|
|
|
|
|
|
Your content is placed more prominently in the result list, if the content has successfully undergone our peer review process. To this end, you can ask for "Peer Reviewing" by selecting the respective menu entry (only visible, when logged in). |
|
|
\ No newline at end of file |
