en/publishers/howto.md

+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).
+
+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 this project.
+
+[[_TOC_]]
+
+
+## 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 reuse of content
+
+Additionally for images:
+ 1. Some editable format that can be reused and adapted by other users: e.g. PlantUML (as used here 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 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](documentation/Sharing from Artemis)).
+
+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**) Format
+ 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 a potential users. Most probably 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)
+
+## 3. Decide on the structure of your contribution
+
+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 content of your contribution beyond the description in the metadata.
+ 3. for complex content of exercises we _recommend_ the following folder structure:
+    a. an **exercise** folder: should contain all basic files, a student needs to start solving the exercise
+    b. a **solution** folder: should contain the sample solution of the exercise
+    c. a **test** folder: should contain the infrastructure to test a submitted exercise for its validity
+ 4. any futher 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 project private and open it only for a certain group of members. The sharing platform cares for the appropriate group memberships of all its users.
+
+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 also every parent group must be public.
+
+## 5. Provide helpful metadata
+
+The metadata.yaml is _mandatory_ (alternatively a metadata.yml or a metadata.js is also appropriate).
+It contains information about your exercise, necessary to discover it by an interested user.
+
+The details of the content can be found [here](technical/MetaData Documentation).
+
+We list here the most relevant content. Please feel free to add further attributes.
+```yaml
+metadataVersion: "0.2"
+type: 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: 
+  - artemis
+structure: atomic
+language:
+  - de
+programmingLanguage:
+  - C
+creator:
+  - name: Priller Simon
+    affiliation: "Universität Innsbruck"
+    email: e.mail@somewhere.edu
+  - name: Kaltenbrunner Lukas
+    affiliation: "Universität Innsbruck"
+    email: e.mail2@somewhere.edu
+difficulty: simple
+image: "https://en.wikipedia.org/wiki/C_(programming_language)#/media/File:The_C_Programming_Language_logo.svg"
+
+```
+
+**metadataVersion**: is currently fixed to "0.2". The version may evolve over time. We will try to provide aids to upgrade the meta data automatically.
+
+**type**: Enumeration. Can be one of `programming exercise`, `exercise`, `collection` or `other`.
+
+**title**: just a nice title. Will be the most visible attribute of your contribution.
+
+**description**: a one or two sentences synopsis of your contribution. Will be displayed as a summary.
+
+**format**: a list that indicates the major file type(s): e.g. `latex`, `doc`, `ppt`, or special formats as e.g. `artemis`
+
+**license**: The name of the license, under which you provide your material. We currently recommend `CC-SA-BY 4.0`
+
+**keyword**: A list of keywords, helping to find and to describe your contribution
+
+**structure**: Enumeration: `atomic` for a single exercise or `collection` for a set of exercises (e.g. a complete course). (`collection` is not yet supported).
+
+**language**: either `de` or `en` (or both, if bi-lingual)
+
+**programmingLanguage**: (optional) the programming language for this exercise: e.g. `C` or `Java`
+
+**creator**: one or more authors for this material: the name, institution and email
+
+**difficulty**: The difficulty of the exercise: One of `simple`, `medium`, `advanced`
+
+**image**: A link to an illustrative image for this course. It will be displayed prominently next to the title of your contribution.
+
+There are further attributes to describe your contribution in more detail.
+
+## 6. Maintain your contents
+
+Everytime you commit your content in the master branch, the project is checked for the presence of `metadata.yaml`. If it is not present, or its content is not valid, you will get an error mail, pointing out the problem.
+
+As long as there are errors in you meta data, the last valid version is reused (or it is not listed at all, if no previous valid version exists). So please correct these errors.
+
+Please take care for your contribution 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). In the future we will also provide better infrastructure (e.g. discussion forums) to exchange with potential user's of your contribution, or to review your content by quality assurance.
\ No newline at end of file