docs: Update the user guide (DEV-1049) (#769)

* docs: Update links and replace header screen shot * docs: Update the project section * docs: Update first screen shot in the system section * docs: Replace source by resource in the data section + replace link 1 * docs: Add section about the creation of a new resource * docs: Add content, update titles, comment out non-relevant content * docs: Add content about the linkage * docs: Replace screen shots in the full text section * docs: Update screen shots of the advanced search section * docs: Update screen shots of the expert section * docs: Update screen shot of the search result section * docs: Update legend links of the search modes to the app * docs: Update the compare view section + display a resource * docs: Fix typo * docs: Remove the section Display more than one resource + update title * docs: Update the section Display data * docs: Fix typo * docs: Add content in the section Add new data + Display properties * docs: Add the section Edit data * docs: Add section about the data permissions * docs: Add section Delete data * docs: Add section Share your data * docs: Add new content to the section Annotate * docs: Update user management page * docs: Update layout * docs: Update page user profile * docs: Add new section about the region + images * docs: Add content in the sections about the region * docs: Fix typo and made changes according to Mike's review Co-authored-by: flaurens <flavie.laurens@unibas.ch>
dasch-swiss · Jul 19, 2022 · 12d0edc · 12d0edc
1 parent 494cbd6
commit 12d0edc
Show file tree

Hide file tree

Showing 50 changed files with 241 additions and 119 deletions.
diff --git a/docs/assets/images/access_annotation_panel.png b/docs/assets/images/access_annotation_panel.png
diff --git a/docs/assets/images/add-new-resource-value.png b/docs/assets/images/add-new-resource-value.png
diff --git a/docs/assets/images/add-new-text-value.png b/docs/assets/images/add-new-text-value.png
diff --git a/docs/assets/images/add-value.png b/docs/assets/images/add-value.png
diff --git a/docs/assets/images/advanced-search-linked-resource.png b/docs/assets/images/advanced-search-linked-resource.png
diff --git a/docs/assets/images/advanced-search-match.png b/docs/assets/images/advanced-search-match.png
diff --git a/docs/assets/images/advanced-search-regex.png b/docs/assets/images/advanced-search-regex.png
diff --git a/docs/assets/images/comment-value.png b/docs/assets/images/comment-value.png
diff --git a/docs/assets/images/compare-resource-select.png b/docs/assets/images/compare-resource-select.png
diff --git a/docs/assets/images/compare-resource-view.png b/docs/assets/images/compare-resource-view.png
diff --git a/docs/assets/images/copy-ark.png b/docs/assets/images/copy-ark.png
diff --git a/docs/assets/images/create-new-res-btn.png b/docs/assets/images/create-new-res-btn.png
diff --git a/docs/assets/images/create-new-resource-form-step1.png b/docs/assets/images/create-new-resource-form-step1.png
diff --git a/docs/assets/images/create-new-resource-form-step2.png b/docs/assets/images/create-new-resource-form-step2.png
diff --git a/docs/assets/images/dashboard-header.png b/docs/assets/images/dashboard-header.png
diff --git a/docs/assets/images/delete-erase-resource.png b/docs/assets/images/delete-erase-resource.png
diff --git a/docs/assets/images/delete-value.png b/docs/assets/images/delete-value.png
diff --git a/docs/assets/images/edit-resource-label.png b/docs/assets/images/edit-resource-label.png
diff --git a/docs/assets/images/edit-value-steps.png b/docs/assets/images/edit-value-steps.png
diff --git a/docs/assets/images/edit-value.png b/docs/assets/images/edit-value.png
diff --git a/docs/assets/images/link_copy_internal_link.png b/docs/assets/images/link_copy_internal_link.png
diff --git a/docs/assets/images/link_edit_value.png b/docs/assets/images/link_edit_value.png
diff --git a/docs/assets/images/link_paste_link.png b/docs/assets/images/link_paste_link.png
diff --git a/docs/assets/images/link_saved_as_standoff.png b/docs/assets/images/link_saved_as_standoff.png
diff --git a/docs/assets/images/project-info.png b/docs/assets/images/project-info.png
diff --git a/docs/assets/images/project-members.png b/docs/assets/images/project-members.png
diff --git a/docs/assets/images/region_annotation_panel.png b/docs/assets/images/region_annotation_panel.png
diff --git a/docs/assets/images/region_draw.png b/docs/assets/images/region_draw.png
diff --git a/docs/assets/images/region_fillin_form.png b/docs/assets/images/region_fillin_form.png
diff --git a/docs/assets/images/region_new_annotation.png b/docs/assets/images/region_new_annotation.png
diff --git a/docs/assets/images/resource-permissions.png b/docs/assets/images/resource-permissions.png
diff --git a/docs/assets/images/resource-view-with-image.png b/docs/assets/images/resource-view-with-image.png
diff --git a/docs/assets/images/search-3modes.png b/docs/assets/images/search-3modes.png
diff --git a/docs/assets/images/search-advanced-link.png b/docs/assets/images/search-advanced-link.png
diff --git a/docs/assets/images/search-expert-link.png b/docs/assets/images/search-expert-link.png
diff --git a/docs/assets/images/search-expert.png b/docs/assets/images/search-expert.png
diff --git a/docs/assets/images/search-fulltext-filterByProject.png b/docs/assets/images/search-fulltext-filterByProject.png
diff --git a/docs/assets/images/search-history.png b/docs/assets/images/search-history.png
diff --git a/docs/assets/images/search-results-list.png b/docs/assets/images/search-results-list.png
diff --git a/docs/assets/images/show-hide-properties.png b/docs/assets/images/show-hide-properties.png
diff --git a/docs/assets/images/system-user-menu.png b/docs/assets/images/system-user-menu.png
diff --git a/docs/assets/images/user-account.png b/docs/assets/images/user-account.png
diff --git a/docs/assets/images/user-edit-profile.png b/docs/assets/images/user-edit-profile.png
diff --git a/docs/assets/images/usermenu-to-userprofile.png b/docs/assets/images/usermenu-to-userprofile.png
diff --git a/docs/assets/images/value-info.png b/docs/assets/images/value-info.png
diff --git a/docs/user-guide/data.md b/docs/user-guide/data.md
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
@@ -6,23 +6,23 @@ This is the documentation for the generic DSP Web Application of the Data and Se
 
 ## Getting started
 
-DSP-APP is an intuitive, easy to use web-based application placed on top of [DSP-API](https://docs.dasch.swiss/developers/dsp-api/documentation/index.md) to directly use its powerful data management functionalities. With this modern web application, the researchers can create their data models, search, browse, and work with their qualitative data as easily as they could with a desktop data management tool. In addition, data models and data will automatically follow accepted standards, be interoperable, findable, and re-usable. Researchers and scholars with small to medium data sets (e.g. PhD research, pilot project, or proof of concept) have access to long-term accessibility to keep their research data alive, guaranteeing longevity of the data.
+DSP-APP is an intuitive, easy to use web-based application placed on top of [DSP-API](https://docs.dasch.swiss/latest/DSP-API/01-introduction/what-is-knora/) to directly use its powerful data management functionalities. With this modern web application, the researchers can create their data models, search, browse, and work with their qualitative data as easily as they could with a desktop data management tool. In addition, data models and data will automatically follow accepted standards, be interoperable, findable, and re-usable. Researchers and scholars with small to medium data sets (e.g. PhD research, pilot project, or proof of concept) have access to long-term accessibility to keep their research data alive, guaranteeing longevity of the data.
 
 ---
 
 ## Login
 
-To login, click on the LOGIN button of the header (right side), a login form will appear. Fill in the form with your credentials (user name or email and password).
-
 ![Get access to the login form.](../assets/images/dashboard-header.png)
 
-In case of a forgotten password, please contact the [DaSCH Team](https://dasch.swiss/team).
+To login, click on the LOGIN button of the header (right side), a login form will appear. Fill in the form with your credentials (user name or email and password).
+
+In case of a forgotten password, please contact the [DaSCH team](mailto:support@dasch.swiss).
 
 ---
 
 ## Registration
 
-You can use the DSP-APP with restricted access as guest. Otherwise, you'll need a login. At the moment, you have to contact the [DaSCH Team](https://dasch.swiss/team) to get your login credentials. In the future (end of 2020), we will support the [SWITCH edu-ID](https://www.switch.ch/edu-id/).
+You can use the DSP-APP with restricted access as guest. Otherwise, you'll need a login. At the moment, you have to contact the [DaSCH team](mailto:support@dasch.swiss) to get your login credentials.
 
 ---
 

diff --git a/docs/user-guide/project.md b/docs/user-guide/project.md
@@ -2,7 +2,7 @@
 
 ## Project
 
-Once you are [logged in](/user-guide/#login), the dashboard displays the list of your project(s). If you are a project administrator or a system administrator, you can edit the project information or archive your project from the project menu. Archived projects are stored in a list on your dashboard and they can be "reactivated" at any time.
+Once you are [logged in](https://docs.dasch.swiss/latest/DSP-APP/user-guide/#login), the dashboard displays the list of your project(s). If you are a project administrator or a system administrator, you can edit the project information or archive your project from the project menu. Archived projects are stored in a list on your dashboard and they can be "reactivated" at any time.
 
 ![Project list and project menu](../assets/images/dashboard.png)*<https://admin.dasch.swiss/dashboard> - By clicking on the project name, you get access to the full project information.*
 
@@ -16,21 +16,19 @@ As project administrator or system administrator, you can define your project, a
 
 ---
 
-## Collaboration
+## Project members
 
-As a system administrator, you can add users as project members and define their permissions roles: *Who is able to edit or to see your project data?* Data includes the research sources and their metadata. [Permissions](/user-guide/project/#permission-groups) can be set for the entire project or for single metadata fields. 
+As a system administrator, you can add users as project members. A user menu with different actions is accessible for each member of the project (the three-dot icon to the right side of the user line). The admin can grant another user as project admin (or remove this permission), edit user's information, change user's password if forgotten, and remove a user from the project.
 
-A user menu with different actions is accessible for each member of the project (link to the right side of the user line). The admin can appoint another user as project admin (or remove this permission), edit user's information, change user's password if forgotten, and remove a user.
+![Collaboration page](../assets/images/project-members.png)*<https://admin.dasch.swiss/project/0803/collaboration> - Project members page where project admin and system admin can add new user to the team.*
 
-![Collaboration page](../assets/images/project-collaboration.png)*<https://admin.dasch.swiss/project/0803/collaboration> - Collaboration page where project admin and system admin can add new user to the team.*
-
-> **_NOTE:_** **Permissions for project admins to add new users as project member will be implemented soon.**
+<!-- >> **_NOTE:_** **Permissions for project admins to add new users as project member will be implemented soon.** -->
 
 ---
 
 ## Data model
 
-The definition of the data model (*ontology*) is the most important step. The data model is indispensable for structuring your data. Our platform provides a tool for an easy creation of one or more project data models. First, you have to know which data and sources you want to work with. The data model can be flexible and customizable. 
+The definition of the data model (*ontology*) is the most important step. The data model is indispensable for structuring your data. Our platform provides a tool for an easy creation of one or more project data models. First, you have to know which data and resources you want to work with. The data model can be flexible and customizable.
 
 The question which you have to answer before you create your data model is **according to which criteria do you organize your data**? In this respect it may be useful to ask yourself:
 
@@ -39,7 +37,6 @@ The question which you have to answer before you create your data model is **acc
 
 As soon as you have come to a conclusion concerning the structure of your data, you're all set to create your data model.
 
-
 ### Create your data model
 
 **Go to *Data model* and click *New data model***
@@ -50,7 +47,6 @@ Go to your project, select the tab `Data model` (step 1) and click the button `N
 By clicking `New data model`, a dialog box opens:
 ![Define new data model.](../assets/images/Fig3.png)
 
-
 **Create data model**
 
 Now you have to set a unique name (*please consider the NOTE*) and you can add a comment. Push the button `Create` to create your data model.
@@ -120,10 +116,10 @@ You can choose from a selection of the following basic types with various subtyp
 - Location (*Place*; a [geonames-identifier](https://www.geonames.org/))
 - Shape (*color*)
 
-Since in our example you want to add a property for the number of pages of your book, you choose `Number`. Now you will see that you can either choose the type `Decimal`, `Integer` or `Page number` for your property. 
+Since in our example you want to add a property for the number of pages of your book, you choose `Number`. Now you will see that you can either choose the type `Decimal`, `Integer` or `Page number` for your property.
 ![Property types.](../assets/images/Fig14.png)
 
-Page numbers have no decimal places, thus you will selecet `Integer` (or `Page number` which is a special case (s. [next section](#correct-property-selection-in-case-of-special-classes))) as the type for your property. The following window pops up:
+Page numbers have no decimal places, thus you will select `Integer` (or `Page number` which is a special case (s. [next section](#correct-property-selection-in-case-of-special-classes))) as the type for your property. The following window pops up:
 ![Property of integer type.](../assets/images/Fig15.png)
 
 In the field *Property label* add for example *Number of pages*, in the comment section you should add a meaningful explanation. It might also make sense to toggle `Required field?` since every PDF Document consists of a number of pages. If you toggle it, the number of pages MUST be given if you add data to the class *Book* - it would then be a required field, not an optional one and data could only be saved if you add the number of pages.
@@ -194,31 +190,39 @@ To delete a whole data model, you have to click the button `Delete` on the right
 
 In the alert window appearing, you click the red button `Delete`. The data model is now deleted.
 
-
 ## An example
 In the following example we focus on how we can reflect about our data before building our model and how a data model can relate classes to each other.
 
-
 ### Preparing a data model
 You have interviewed 20 people and recorded the interviews. During these interviews you talked about photographs. Among all the data collected during the project, the most important are:
-o	audio-files of the interview
-o	transcribed text of conversations (or transcribe the files within the web application)
-o	photographs
-o	data about the person you interviewed
-o	location where the photograph was taken
 
-The following Diagram 1 shows the initial situation: 
-![Diagram 1: the initial situation.](../assets/images/Fig23.png)*Diagram 1: the initial situation.*
+-	audio-files of the interview
+-	transcribed text of conversations (or transcribe the files within the web application)
+-	photographs
+-	data about the person you interviewed
+-	location where the photograph was taken
+
+The following Diagram 1 shows the initial situation:
+
+![Diagram 1: the initial situation.](../assets/images/Fig23.png)
+
+*Diagram 1: the initial situation.*
 
 The second step will be to consider the hierarchy of the data. How your hierarchy looks like depends on which criteria your data were organized and what your purposes are. It might even be possible that you don’t need a hierarchy as shown in Diagram 1.
 
 In our case, we know that the transcripts are linked to the audio-interviews, persons are linked to interviews and audio-interviews, photographs are linked to audio-interviews and transcripts plus locations are linked to the photographs.
 
 How the practical arrangement finally looks like depends on your purposes and preferences. For example we could choose to arrange the data with regards to their audio source as seen in Diagram 2:
-![Diagram 2: Focus on the audio-interview.](../assets/images/Fig24.png)*Diagram 2: Focus on the audio-interview.*
+
+![Diagram 2: Focus on the audio-interview.](../assets/images/Fig24.png)
+
+*Diagram 2: Focus on the audio-interview.*
 
 However, we can also prefer another visualization which focuses on the transcript (Diagram 3):
-![Diagram 3: Focus on the transcript.](../assets/images/Fig25.png)*Diagram 3: Focus on the transcript.*
+
+![Diagram 3: Focus on the transcript.](../assets/images/Fig25.png)
+
+*Diagram 3: Focus on the transcript.*
 
 We could think of many different hierarchies, lastly it depends on what serves your purposes best. Our next step will be to implement the hierarchy in Diagram 3 in our data model.
 
@@ -229,7 +233,7 @@ First, we create the resource classes that constitute the basic containers of ou
 ![Create resource classes.](../assets/images/Fig26.png)
 
 **2. Relate resource classes**
-According to our Diagram 3, we determined the transcript to be the centre of the hierarchy. In the transcript, the photographs are mentioned, the interviewed person is linked to the transcript and the audio-interview as the raw source is linked to the transcript too. Thus, we have to add photograph, audio-interview and person as properties to the transcript. 
+According to our Diagram 3, we determined the transcript to be the center of the hierarchy. In the transcript, the photographs are mentioned, the interviewed person is linked to the transcript and the audio-interview as the raw resource is linked to the transcript too. Thus, we have to add photograph, audio-interview and person as properties to the transcript.
 
 In the box of *Transcript* click on `+ Add property`:
 ![Add property to resource class.](../assets/images/Fig27.png)

diff --git a/docs/user-guide/system.md b/docs/user-guide/system.md
@@ -38,4 +38,4 @@ For each user, the system admin has access to several actions:
 
 ![System admin can add a user as a member user of a project](../assets/images/system-manage-project-membership.png)
 
-- *Suspend user*: the user is deactivated and has no more access to DSP-APP. The system admin can reactivate it at any time.
+- *Suspend user*: the user is deactivated and no longer has access to DSP-APP. The system admin can reactivate it at any time.
diff --git a/docs/user-guide/user.md b/docs/user-guide/user.md
@@ -1,34 +1,22 @@
 # User Profile
 
-![Get access to your user profile and more](../assets/images/usermenu-to-userprofile.png)*<https://admin.dasch.swiss/dashboard> - Get access to your user profile, collections and  account from the main user menu.*
-
----
-
 ## Your user profile and projects
 
-To change your personal information as well as your default language used by the interface, you can edit your profile clicking *Edit*. Currently, the avatar image comes from gravatar.com (go on their [website](http://en.gravatar.com/) to register if you want your customized user photo).
-
-![Get access to your user profile and more](../assets/images/user-profile.png)*<https://admin.dasch.swiss/projects> - Overview of your user profile and your projects.*
-
-The list of your projects is accessible, click on one project to get more information about it. As project admin, you can also edit or archive your projects, and as system admin, you can additionally create new project on this page.
-
-![Edit user's profile](../assets/images/user-edit-profile.png)*Edit your user profile. The username, the email address and the admin rules are not editable.*
-
----
+To change your personal information as well as your default language used by the interface, you can edit your profile by clicking *Edit my profile*. Currently, the avatar image comes from gravatar.com (go on their <a href="http://en.gravatar.com/" target="_blank">website</a> to register if you want your customized user photo).
 
-## Your collections
+![Get access to your user profile and more](../assets/images/usermenu-to-userprofile.png)*<https://admin.dasch.swiss/dashboard> - Overview of your user profile and your projects.*
 
-&#9888; *NOT YET IMPLEMENTED*
+The list of your projects is accessible from here, click on one project to get more information about it. As a project admin, you can also edit or archive your projects, and as a system admin, you can additionally create new projects.
 
-You will be able to store collections of sources or specific searches to work with them later or share them with collaborators.
+![Edit user's profile](../assets/images/user-edit-profile.png)*Edit your user profile. The username, the email address, and the admin rules are not editable.*
 
 ---
 
 ## Your account
 
-As a matter of security, it is strongly recommended to update your password at least once a year. In your account page, you can update your password.
+As a matter of security, it is strongly recommended to update your password at least once a year. On your account page, you can update your password.
 
 ![Get access to the user account where the user can reset its password and deactivate its own account](../assets/images/user-account.png)*<https://admin.dasch.swiss/account> - Update your password and deactivate your user account.*
 
 &#9888;
-You can delete (deactivate) your own user account. Only a system administrator will be able to reactivate it.
+You can delete (deactivate) your own user account. However, only a system administrator will be able to reactivate it.