en/publishers/howto.md

@@ -43,7 +43,7 @@ For **other material** decide what is best suited for potential users. Most like
 
 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 private folder 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).
+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
 
@@ -54,10 +54,10 @@ You can combine various exercises into a collection, e.g. a complete course, or
 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.
+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
+   - 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.
 
@@ -65,13 +65,13 @@ 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 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.
+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 also every parent group must be public.
+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 available: you can use the special attribute `publicVisibility`, e.g.
+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:
@@ -85,7 +85,7 @@ You can find more information on the help page on [permissons](en/publishers/per
 
 ## 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 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).