add new section & rename

docs/42_adopt_assessments.md

@@ -124,7 +124,7 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass
 
     In the addProperties section, we define each variable that corresponds to a specific assessment. For instance:
     - `"variableName": "phq-9"` is linked to `"isAbout": "activities:PHQ-9/PHQ9_schema"`. This implies that the PHQ-9 schema (an assessment for depressive symptoms) from the reproschema-library is used in the current psychological questionnaire schema.
-    - Similarly, other assessments like GAD-7 and PC-PTSD-5 are included using their respective variable names and links to their schemas in the activities context.
+    - Similarly, other assessments like `GAD-7` and `PC-PTSD-5` are included using their respective variable names and links to their schemas in the activities context.
     - Additional variables related to clinical history in psychiatry are linked using the demo context, pointing to specific items within the demographics and background information section of the reproschema-library.
         ```javascript
         {
@@ -134,3 +134,5 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass
         ```
     - The `order` array specifies the sequence in which these assessments will appear in the questionnaire, ensuring a logical flow for participants.
     - The `shuffle` setting is `false`, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export.
+
+See the outcome [here](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/2_psychological/psychological_questionnaire_schema)

docs/43_create_new_assess.md

@@ -2,12 +2,14 @@
 
 This section provides the customized new assessments tailored to specific research needs. Our focus is on creating three distinct types of activities that are not readily available in the reproschema-library. These include: (1) clinical questions to gather clinical background information, (2) a speech task designed to collect audio data, and (3) an audio check to facilitate the speech task.
 
-For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the `activities` directory. For instance, the speech task resides in `activities/4_speech`. Within this folder, besides the primary schema file (e.g., `speech_schema`), there is an additional subfolder named `items`. This `items` folder contains individual questions or tasks pertaining to that specific activity.
+For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the `activities` directory. For instance, the speech task resides in [`activities/4_speech`](https://github.com/ReproNim/reproschema-demo-protocol/tree/main/activities/4_speech). Within this folder, besides the primary schema file (e.g., `speech_schema`), there is an additional subfolder named `items`. This `items` folder contains individual questions or tasks pertaining to that specific activity.
 
 In the case of the speech task, the `items` folder might include a single task designed to prompt the participant to provide a speech sample. Similarly, for the clinical questions, their respective folders will contain `items` subfolders with corresponding questions tailored to elicit the required information.
+
 The structure of an item within the `items` folder of a ReproSchema activity is similar to the schema template, but with key differences that cater to the specifics of individual data collection elements. Here's an explanation of the provided template for a `country item`:
-1. **Context and type (@context, @type)**: The @context remains the same, pointing to the generic context of ReproSchema. The @type is now "reproschema:Field" instead of "reproschema:Activity". This change signifies that this template defines a single data collection field or question within an activity, as opposed to the overall structure of an activity.
-2. **Identifier and descriptive fields (@id, prefLabel, description, etc.)**: @id serves as a unique identifier for the item, here named "country_item". prefLabel and description provide a human-readable name and a brief description of the item, similar to their use in the schema template.
+
+1. **Context and type (@context, @type)**: The `@context` remains the same, pointing to the generic context of ReproSchema. The `@type` is now "reproschema:Field" instead of "reproschema:Activity". This change signifies that this template defines a single data collection field or question within an activity, as opposed to the overall structure of an activity.
+2. **Identifier and descriptive fields (@id, prefLabel, description, etc.)**: `@id` serves as a unique identifier for the item, here named "country_item". prefLabel and description provide a human-readable name and a brief description of the item, similar to their use in the schema template.
 3. **Question field (question)**: This field contains the actual question or prompt that will be presented to the participant. In this template, it reads: "This is an item where the user can select a country."
 4. **UI configuration (ui)**: The ui section in the item template differs from the schema template. It specifies how the question will be presented to the user. The inputType is set to "selectCountry", indicating that the user interface will provide a country selection method.
 5. **Response options (responseOptions)**: This section defines the nature and structure of the responses allowed for the item. In this example, it specifies the valueType as "xsd:string" and a maxLength of 50 characters. It also provides a URL to a list of choices, in this case, a JSON file containing country names. This link allows the questionnaire to dynamically fetch and display a list of countries as response options.
@@ -21,9 +23,10 @@ The structure of an item within the `items` folder of a ReproSchema activity is
 
 ## Step 1: Specifying `inputType` and `responseOption` to gather precise data
 
-We have crafted ten items in the 'items' folder for the clinical questions assessment. Each item, such as 'alcohol_consumption', 'height', 'weight', etc., has its 'ui' inputType and 'responseOptions' specifically defined to suit the nature of the question.
+We have crafted ten items in the 'items' folder for the clinical questions assessment. Each item, such as `alcohol_consumption`, `height`, `weight`, etc., has its `ui` inputType and `responseOptions` specifically defined to suit the nature of the question.
 
 Take 'alcohol_consumption' as an example. The UI configuration and response options for this question are tailored to capture a straightforward piece of information:
+
 ```javascript
 "question": {
     	"en": "Have you drunk alcohol today?",
@@ -57,7 +60,8 @@ Take 'alcohol_consumption' as an example. The UI configuration and response opti
 - In the responseOptions, the `valueType` is defined as `"xsd:string"`, signifying that the expected type of response is a string. The multipleChoice field is set to false, indicating that participants can only select one of the provided options.
 - The `choices` array lists the possible responses. In this case, there are two: "Yes" and "No", each with a corresponding value (1 for Yes, 2 for No) and translations provided for English ("en") and Spanish ("es").
 
-For the speech task in our demo project, the configuration of ui `inputType` and `responseOptions` is distinctively tailored to facilitate audio data collection:
+- For the speech task in our demo project, the configuration of ui `inputType` and `responseOptions` is distinctively tailored to facilitate audio data collection:
+
     ```javascript
     "ui": {
         "inputType": "audioPassageRecord"
@@ -80,10 +84,11 @@ We can integrate additional components tailored to the unique requirements of sp
 
 1. Setting up an audio check for the speech task
 
-    To ensure the effectiveness of our speech task, we create an activity for audio verification within the `activities` folder, naming it `0_audio`.
-    This folder contains the `audio_check_schema`, a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants.
+    To ensure the effectiveness of our speech task, we create an activity for audio verification within the `activities` folder, naming it [`0_audio`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/).
+    This folder contains the [`audio_check_schema`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/audio_check_schema), a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants.
 
 2. Contextual and properties configuration for audio check
+
     ```javascript
      "@context": [
         "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic",

docs/44_setup_feedback.md

@@ -24,7 +24,7 @@ To conclude our protocol, we integrate a customized feedback activity. This choi
 }
 ```
 
-The `feedback` item in this activity (`5_feedback`) is specifically designed to gather open-ended responses, allowing participants to share their thoughts and suggestions:
+The `feedback` item in this activity ([`5_feedback`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/5_feedback/items/feedback)) is specifically designed to gather open-ended responses, allowing participants to share their thoughts and suggestions:
 
 - Item Structure: The item `feedback` is set up with an identification and purpose, indicated by its '@id' and descriptive fields.
 - Question Prompt: The `question` is presented in both English and Spanish, encouraging participants to provide comments on their study experience. It’s formatted to be inclusive, giving participants the option to skip if they choose.

docs/45_finalize_protocol.md

@@ -1,28 +1,33 @@
 # Finalizing the Protocol
 
-After setting up individual activities, we return to the main protocol schema to organize everything cohesively. This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach:
+After setting up individual activities, we return to the main [protocol schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema) to organize everything cohesively. This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach:
+
 1. Context and protocol definition
 
-    The '@context', '@type', '@id', and descriptive fields ('prefLabel', 'description', etc.) provide the foundational information about the protocol.
+    The `@context`, `@type`, `@id`, and descriptive fields (`prefLabel`, `description`, etc.) provide the foundational information about the protocol.
 
 2. Inclusion of activities
 
-    The ui section's addProperties array is crucial. Here, each activity schema we've created is referenced under 'isAbout', with its respective 'variableName' and 'prefLabel'. For example, the consent activity is linked as 
+    The ui section's addProperties array is crucial. Here, each activity schema we've created is referenced under `isAbout`, with its respective `variableName` and `prefLabel`. For example, the `audio` activity is linked as 
     ```javascript
     {
-        "isAbout": "../activities/0_consent/consent_schema", 
-        "variableName": "consent_schema", 
-        "prefLabel": {"en": "Sign Consent"}
+        "isAbout": "../activities/0_audio/audio_check_schema",
+        "variableName": "audio_check_schema",
+        "prefLabel": {"en": "Audio Check"}
     }
     ```
     This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback.
 
-2. Order of presentation
+2. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50)
 
     The order array within ui specifies the sequence in which these activities will appear in the protocol. It's arranged to flow logically from consent, through various assessments, to the final feedback, ensuring a structured participant experience. For instance, the order starts with `../activities/0_audio/audio_check_schema` and progresses through to `../activities/5_feedback/feedback_schema`.
 
-3. Additional UI settings:
+3. [Additional UI settings](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L23)
     - 'shuffle' is set to false to maintain the specified order.
     - 'allow' includes functionalities such as 'reproschema:AllowExport' for data exporting options.
+
+4. Update [README.md](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/README.md)
+
+    Give clear and concise instructions on what this protocol is about and how participants should use it.
 	
 Upon finalizing our protocol with the integrated activities, the end result is a fully interactive research tool hosted on our GitHub repository. For data collection, this tool can be linked to a backend server, or participants can be given the option to export their data directly.

docs/46_tools.md

@@ -0,0 +1,5 @@
+# Converting between ReproSchema and REDCap
+
+In the world of research data management, flexibility and compatibility are key. Understanding this, we provide specialized tools designed to seamlessly convert data between ReproSchema format and REDCap CSV format. Whether you're transitioning from REDCap to ReproSchema or vice versa, these tools ensure a smooth and efficient conversion process, preserving the integrity and structure of your data.
+
+For detailed instructions on how to use these conversion tools, please visit [reproschema-py](https://github.com/ReproNim/reproschema-py). This link provides comprehensive guidance on usage, ensuring you can easily adapt your data to the format best suited for your research needs.

mkdocs.yml

@@ -19,12 +19,13 @@ nav:
   - Introduction: "01_introduction.md"
   - Project structure: "20_project_structure.md"
   - Schema: "30_schema.md"
-  - How-To-Guide:
+  - User Guide:
       - Create a research protocol: "41_create_new_protocol.md" 
       - Adopt assessments from the library: "42_adopt_assessments.md" 
       - Create new assessments for a protocol: "43_create_new_assess.md"
       - Add a feedback section: "44_setup_feedback.md"
       - Finalize the protocol: "45_finalize_protocol.md"
+      - Additional tools: "46_tools.md"
 
   # - Creating a new activity and protocol: "create_new_activity_protocol.md"
   # - Testing your schema and collecting data: "testing_using_schema.md"