docs: update user documentation with custom organisation categories

research-software-directory · Oct 17, 2024 · 6ee1b57 · 6ee1b57
1 parent e32a7ec
commit 6ee1b57
Show file tree

Hide file tree

Showing 10 changed files with 93 additions and 57 deletions.
diff --git a/documentation/assets/screenshots-template.xcf b/documentation/assets/screenshots-template.xcf
diff --git a/documentation/docs/01-users/05-adding-software.md b/documentation/docs/01-users/05-adding-software.md
@@ -34,24 +34,24 @@ Another section with subtitle
 
 ## Code area
 
-Use `three backticks` to create code area
+Use `three backticks` to create a code area
 
-``bash
+`bash
 This example is code area
-``
+`
 
 ## Simple table
 
-|column 1| column 2| column 3|
-|-|-|-|
-|123242|234234|3|
-|some text here|34|x=23|
+| column 1       | column 2 | column 3 |
+| -------------- | -------- | -------- |
+| 123242         | 234234   | 3        |
+| some text here | 34       | x=23     |
 
 ## Task list
 
-* [x] Do this first
-* [ ] Then this
-* [ ] And this at last
+- [x] Do this first
+- [ ] Then this
+- [ ] And this at last
 
 ## Links
 
@@ -62,7 +62,6 @@ This example is code area
 You need to use the full URL of the image and the image needs to send CORS headers, otherwise the image will not be loaded
 
 ![Mozilla](https://cdn.glitch.me/4c9ebeb9-8b9a-4adc-ad0a-238d9ae00bb5%2Fmdn_logo-only_color.svg)
-
 ```
 
 ### Document URL
@@ -89,8 +88,8 @@ The software logo is shown on the software page and in the software card (see ex
 
   The RSD supports URLs starting with https that point to the repository website, or to the actual git repository, for example:
 
-  * `https://github.com/research-software-directory/RSD-as-a-service` (website)
-  * `https://github.com/research-software-directory/RSD-as-a-service.git` (git repository)
+  - `https://github.com/research-software-directory/RSD-as-a-service` (website)
+  - `https://github.com/research-software-directory/RSD-as-a-service.git` (git repository)
 
 - A **Getting started URL** which refers to webpage with more information about the software. This is shown as the "Get started" button on the software page.
 
@@ -149,13 +148,24 @@ If you have provided a **Software DOI** in the previous section, you can import
 
 :::
 
-## Organisations
+## Participating organisations
 
 In this section, you can list which organisations contributed to the development of the software. You can use the search bar underneath "Add organisation" to search for
 organisations already registered in the RSD or in the [ROR](https://ROR.org) database.
 
 ![video](img/software-organisation.gif)
 
+### Organisation categories
+
+If the maintainers of the organisation have created custom categories, you will see **an additional modal asking you to select organisation specific categories that apply to your software**.
+
+:::tip
+
+- Custom organisation categories will be shown on the software page below the logo and before the keywords. Use the "View Software" button to see how custom organisation categories are displayed on the software page.
+- You can change the custom organisation categories using the categories button.
+
+:::
+
 ## Mentions
 
 This section allows you to add mentions to your software page. You can use this to list reference papers, publications, presentations, videos, blogs, etc. that prominently feature your software, or the results produced by your software.
@@ -164,7 +174,7 @@ This section allows you to add mentions to your software page. You can use this
 
 ### Reference papers
 
-Use the *Search* box on the right hand side to find papers by DOI, OpenAlex ID or title. All the relevant data about the publication will be retrieved automatically. A background scraper will use [OpenAlex](https://openalex.org/) to collect all citations of reference papers that have a DOI or an OpenAlex ID.
+Use the _Search_ box on the right hand side to find papers by DOI, OpenAlex ID or title. All the relevant data about the publication will be retrieved automatically. A background scraper will use [OpenAlex](https://openalex.org/) to collect all citations of reference papers that have a DOI or an OpenAlex ID.
 
 ### Citations
 
@@ -176,7 +186,7 @@ You cannot edit the content of this section. All entries are automatically harve
 
 ### Related output
 
-Here you can add all additional related output. Use search to find papers or other publications by DOI, OpenAlex ID or title. It is also possible to bulk add mentions, that have a DOI (use the *Import* button). On the popup, you can add one DOI per line, with a maximum of 50. After clicking on the *Next* button, we will fetch the data, which can take a moment. When that is done, you will see an overview of the data we fetched, including possible errors, where you can check the data and possibly disable some of the mentions.
+Here you can add all additional related output. Use search to find papers or other publications by DOI, OpenAlex ID or title. It is also possible to bulk add mentions, that have a DOI (use the _Import_ button). On the popup, you can add one DOI per line, with a maximum of 50. After clicking on the _Next_ button, we will fetch the data, which can take a moment. When that is done, you will see an overview of the data we fetched, including possible errors, where you can check the data and possibly disable some of the mentions.
 
 ## Testimonials
 
@@ -190,7 +200,7 @@ If your software is available through a package manager like Anaconda, PyPi or D
 
 We currently support the following package managers: [Anaconda](https://anaconda.org/), [Cran](https://cran.r-project.org/web/packages/index.html), [Chocolatey](https://community.chocolatey.org), [Debian](https://packages.debian.org), [Docker Hub](https://hub.docker.com/search?q=), [GitHub](https://github.com), [Gitlab](https://gitlab.com), [Go](https://pkg.go.dev), [Maven](https://mvnrepository.com/), [npm](https://www.npmjs.com/), [PyPI](https://pypi.org/), [Rust](https://crates.io), [Sonatype](https://central.sonatype.com/), [Snapcraft](https://snapcraft.io).
 
-If your package manager is not listed above, you can still add it, but we will categorise it as *other* and cannot scrape it yet. You can [open an GitHub issue](https://github.com/research-software-directory/RSD-as-a-service/issues) (please check for existing issues first) or contact us if you want us to support an additional package manager.
+If your package manager is not listed above, you can still add it, but we will categorise it as _other_ and cannot scrape it yet. You can [open an GitHub issue](https://github.com/research-software-directory/RSD-as-a-service/issues) (please check for existing issues first) or contact us if you want us to support an additional package manager.
 
 ![video](img/software-package-managers.gif)
 

diff --git a/documentation/docs/01-users/07-adding-projects.md b/documentation/docs/01-users/07-adding-projects.md
@@ -8,7 +8,7 @@ After signing in, use the **"+"** button next to your avatar icon on the top rig
 
 ![image](img/new-project.gif)
 
-The RSD will automatically generate a *slug* for your project based on the project name you have provided. This slug will become part of the URL on which your project page can be found.
+The RSD will automatically generate a _slug_ for your project based on the project name you have provided. This slug will become part of the URL on which your project page can be found.
 There is a small chance the generated slug is already in use by another project. If this is the case, an error will be shown, and you will need to change the slug manually to resolve this conflict.
 
 Once you click **"save"**, the RSD will initialize a new empty project page. This page will not be public yet to give you some time to provide additional information. Next, you can add additional information in the edit sections explained below.
@@ -63,7 +63,7 @@ project. Therefore, you can safely change information about this person without
 When manually adding team members or adding images or email addresses of persons, please ensure you have **permission** to share this information!
 :::
 
-## Participating Organisations
+## Participating organisations
 
 ![image](img/project-add-organisation.webp)
 
@@ -83,6 +83,17 @@ Regular users cannot update an organisation after adding it to the RSD. Only the
 information. Please [contact us](mailto:[email protected]) if you need to update organisation information.
 :::
 
+### Organisation categories
+
+If the maintainers of the organisation have created custom categories, you will see **an additional modal asking you to select organisation specific categories that apply to your project**.
+
+:::tip
+
+- Custom organisation categories will be shown on the project page below the keywords. Use the "View Project" button to see how custom organisation categories are displayed on your project page.
+- You can change the custom organisation categories using the categories button.
+
+:::
+
 ## Mentions
 
 In this section, you can add mentions to your project. These entries may consist of other research outputs such as publications, dataset, book sections, blogs, etc. Where **Output** typically consists of research output being produced by the project team itself, **Impact** is generally triggered by events outside the project, such as re-use of results in other projects, publications, or society, items in the media, etc.

diff --git a/documentation/docs/01-users/07-adding-projects.md.license b/documentation/docs/01-users/07-adding-projects.md.license
@@ -1,6 +1,6 @@
 SPDX-FileCopyrightText: 2022 - 2024 Netherlands eScience Center
 SPDX-FileCopyrightText: 2022 Jason Maassen (Netherlands eScience Center) <[email protected]>
-SPDX-FileCopyrightText: 2023 Dusan Mijatovic (Netherlands eScience Center)
+SPDX-FileCopyrightText: 2023 - 2024 Dusan Mijatovic (Netherlands eScience Center)
 SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <[email protected]>
 SPDX-FileCopyrightText: 2024 Dusan Mijatovic (dv4all) (dv4all)
 SPDX-FileCopyrightText: 2024 Ewan Cahen (Netherlands eScience Center) <[email protected]>

diff --git a/documentation/docs/01-users/09-organisation.md b/documentation/docs/01-users/09-organisation.md
@@ -9,29 +9,30 @@ If you would like to claim an organisation, please have a look at [Register or c
 
 ## What can organisation maintainers do?
 
-The RSD distinguishes between __primary__ and __invited maintainers__.
+The RSD distinguishes between **primary** and **invited maintainers**.
 Here is an overview of what each of them can do:
 
-|                                        | Primary maintainer | Invited maintainer |
-|----------------------------------------|:------------------:|:------------------:|
-| Edit About section                     |         x          |         x          |
-| Upload/delete logo                     |         x          |         x          |
-| Edit organisation metadata             |         x          |         x          |
-| Reject affiliations (software/project) |         x          |         x          |
-| Pin/unpin software/projects            |         x          |         x          |
-| Invite maintainers                     |         x          |         x          |
-| Remove maintainers (not primary)       |         x          |         x          |
-| Add new research units                 |         x          |                    |
-| Remove/change primary maintainer *     |                    |                    |
-| Change organisation URL path *         |                    |                    |
-| Set parent organisation *              |                    |                    |
-| Set as official member *               |                    |                    |
-
-(*) These actions can only be performed by administators (see [Administration section](/rsd-instance/administration/#edit-organisation)). If necessary, contact us via [[email protected]](mailto:[email protected]).
+|                                         | Primary maintainer | Invited maintainer |
+| --------------------------------------- | :----------------: | :----------------: |
+| Edit About section                      |         x          |         x          |
+| Upload/delete logo                      |         x          |         x          |
+| Edit organisation metadata              |         x          |         x          |
+| Reject affiliations (software/project)  |         x          |         x          |
+| Pin/unpin software/projects             |         x          |         x          |
+| Invite maintainers                      |         x          |         x          |
+| Remove maintainers (not primary)        |         x          |         x          |
+| Create and edit organisation categories |         x          |         x          |
+| Add new research units                  |         x          |                    |
+| Remove/change primary maintainer \*     |                    |                    |
+| Change organisation URL path \*         |                    |                    |
+| Set parent organisation \*              |                    |                    |
+| Set as official member \*               |                    |                    |
+
+(\*) These actions can only be performed by administators (see [Administration section](/rsd-instance/administration/#edit-organisation)). If necessary, contact us via [[email protected]](mailto:[email protected]).
 
 ## My organisations
 
-To see a list of organisations you are a maintainer of use __My organisations__ option in your __profile menu__.
+To see a list of organisations you are a maintainer of use **My organisations** option in your **profile menu**.
 
 ![Screenshot of user menu](img/menu-my-organisations.webp)
 
@@ -45,12 +46,16 @@ You can upload a new logo or remove it.
 The RSD supports common image formats, e.g. jpg, png or svg.
 
 :::tip
-If possible, please upload an __SVG__ version of your organisation's logo for optimal visual presentation within the RSD.
+If possible, please upload an **SVG** version of your organisation's logo for optimal visual presentation within the RSD.
 :::
 
-## General settings
+## Settings
 
-Under __"Settings - General settings"__ you can edit:
+The organisation settings has following sections: General settings, Categories, Maintainers and About page.
+
+### General settings
+
+Under **General settings** you can edit:
 
 - Name: displayed in the organisation card and in the header of the organisation page
 - Short description: displayed in the organisation card and in the header of the organisation page
@@ -59,15 +64,21 @@ Under __"Settings - General settings"__ you can edit:
 
 ![Screenshot of organisation settings](img/organisation-settings.webp)
 
-## Manage maintainers
+### Categories
+
+Each RSD organisation can define a set of custom categories to be assigned to software and/or projects. When a software/project maintainer adds this RSD organisation to their page, an additional modal is shown to software/project maintainer to assign specific organisation categories to the software/project. These organisation specific categories are shown on the software/project page.
+
+![Screenshot of organisation categories](img/organisation-categories.webp)
+
+### Manage maintainers
 
 As a maintainer, you can invite or remove other maintainers from your organisation.
 
 :::warning
-The __primary maintainer__ of an organisation is set by RSD administrators. If you want to change the primary maintainer, contact us via [[email protected]](mailto:[email protected]).
+The **primary maintainer** of an organisation is set by RSD administrators. If you want to change the primary maintainer, contact us via [[email protected]](mailto:[email protected]).
 :::
 
-To invite new maintainers, click on __"Generate invite link"__. A link will be generated. You can either copy this link or click on "Email this invite" to open your mail program with a pre-formulated email.
+To invite new maintainers, click on **"Generate invite link"**. A link will be generated. You can either copy this link or click on "Email this invite" to open your mail program with a pre-formulated email.
 
 :::info
 
@@ -78,10 +89,10 @@ To invite new maintainers, click on __"Generate invite link"__. A link will be g
 
 ![animation](img/organisation-maintainer-invite.gif)
 
-## About page
+### About page
 
-In the __"About"__ section, relevant information about your organisation can be added in a free text form.
-To edit the content of the section, please navigate to __"Settings"__ and scroll down to the __"About"__ section.
+In the **"About"** section, relevant information about your organisation can be added in a free text form.
+To edit the content of the section, please navigate to **"Settings"** and scroll down to the **"About"** section.
 The text can be formatted using [Markdown syntax](https://www.markdownguide.org/basic-syntax/).
 
 :::tip
@@ -92,7 +103,7 @@ If there is no content for the About page, the page will not be shown.
 
 ## Pin software or project
 
-To pin specific software or project to the start of the respective list, click on the three dots in the upper right corner of a software or project card and click on __Pin software__ / __Pin project__. It will then be shown at the beginning of the list. If you no longer want to pin a software or project, click on the dots in the software card and click __Unpin software__ / __Unpin project__.
+To pin specific software or project to the start of the respective list, click on the three dots in the upper right corner of a software or project card and click on **Pin software** / **Pin project**. It will then be shown at the beginning of the list. If you no longer want to pin a software or project, click on the dots in the software card and click **Unpin software** / **Unpin project**.
 
 :::tip
 The "Pinned" order is the default order applied when visiting organisation page.
@@ -102,7 +113,7 @@ The "Pinned" order is the default order applied when visiting organisation page.
 
 ## Deny affiliations
 
-An organisation maintainer can deny affiliations with software or project. To do this, open the context menu of the respective software or project, and click on __Block affiliation__.
+An organisation maintainer can deny affiliations with software or project. To do this, open the context menu of the respective software or project, and click on **Block affiliation**.
 
 :::tip
 When the affiliation with an entry has been denied
@@ -112,29 +123,29 @@ When the affiliation with an entry has been denied
 - the entry will not be included in the metrics of the organisation
 - the organisation will be shown with "Blocked" icon on the edit page of the item (software or project)
 - the denied affiliation is visible to the organisation and the software/project maintainers
-:::
+  :::
 
 ![animation](img/organisation-block-affiliation.gif)
 
 ## Add research units
 
 The RSD is capable of representing the organisational structure of an organisation.
-The structure is represented using __Research units__. A research unit has the same properties as an organisation and is maintained in the same manner, except for the fact that it has a parent organisation and is not listed on the organisations overview grid.
+The structure is represented using **Research units**. A research unit has the same properties as an organisation and is maintained in the same manner, except for the fact that it has a parent organisation and is not listed on the organisations overview grid.
 
 It is possible to create several levels of nested research units.
 
 :::warning
-Research units can only be added by the __primary maintainer__.
+Research units can only be added by the **primary maintainer**.
 :::
 
-To create new research units, navigate to the __Research units__ in the sidebar, and click on the __+ Add__ button in the upper right corner. You will be presented with a modal:
+To create new research units, navigate to the **Research units** in the sidebar, and click on the **+ Add** button in the upper right corner. You will be presented with a modal:
 
 ![Screenshot](img/organisation-add-unit.webp)
 
 The RSD path (second input field) will be automatically populated while the name is ist typed, but can be adjusted afterwards.
 
 :::warning
-You cannot edit the __RSD Path__ afterwards.
+You cannot edit the **RSD Path** afterwards.
 :::
 
 If possible, a logo and a website URL can be added as well.

diff --git a/documentation/docs/01-users/09-organisation.md.license b/documentation/docs/01-users/09-organisation.md.license
@@ -1,6 +1,6 @@
+SPDX-FileCopyrightText: 2023 - 2024 Dusan Mijatovic (Netherlands eScience Center)
 SPDX-FileCopyrightText: 2023 - 2024 Ewan Cahen (Netherlands eScience Center) <[email protected]>
 SPDX-FileCopyrightText: 2023 - 2024 Netherlands eScience Center
-SPDX-FileCopyrightText: 2023 Dusan Mijatovic (Netherlands eScience Center)
 SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <[email protected]>
 SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
 

diff --git a/documentation/docs/01-users/img/organisation-categories.webp b/documentation/docs/01-users/img/organisation-categories.webp