de/publishers/howto.md

@@ -4,7 +4,12 @@ _Diese Seite gibt es derzeit leider nur auf Englisch._
 
 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.
+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
 
@@ -13,22 +18,21 @@ You share your material via a gitlab repository. So there are little technical r
 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
+ 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
+ 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 (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
-
+    - 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**) Format
+ 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
@@ -38,13 +42,13 @@ For **other material** decide what is best suited for a potential users. Most pr
 ## 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)
+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/...)
 
 ## 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".
+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.
@@ -59,12 +63,22 @@ In order to provide future services we would propose the following structure:
 
 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.
+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 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.
 
+For private projects there is an explicit mechanism to make only parts of the project publicly available: 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```.
+
 ## 5. Provide helpful metadata
 
 The metadata.yaml is _mandatory_ (alternatively a metadata.yml or a metadata.js is also appropriate).
@@ -118,7 +132,7 @@ subject:
   - "Universität Innsbruck-Einführung in die Programmierung"
 ```
 
-Please refer to the documentation of [metadata version 0.4](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/Metadata-Version-0.4-Documentation) for a full reference of the available fields.
+Please refer to the documentation of [metadata version 0.4](https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/Metadata-Version-0.4-Documentation) for a full up-to-date reference of the available fields.
 
 ## 6. Maintain your contents