Merge pull request #399 from Remi-Gau/remi-documentation

[DOC] Update documentation

docs/20_project_structure.md

@@ -33,7 +33,7 @@ The ReproSchema is like a blueprint for research projects, ensuring everyone col
 
 There is also an [`example`](https://github.com/ReproNim/reproschema/tree/master/examples)
 schema that can help give you a quick overview of what the protocol and activity
-for a study might look like. For more details see the [schema section](../docs/30_schema.md).
+for a study might look like. For more details see the [schema section](30_schema.md).
 
 ## [reproschema-library](https://github.com/ReproNim/reproschema-library)
 
@@ -72,7 +72,7 @@ You can see it in action [here](https://www.repronim.org/reproschema-ui/)
 
 ## [reproschema-protocol-cookiecutter](https://github.com/ReproNim/reproschema-protocol-cookiecutter)
 
-The reproschema-protocol-cookiecutter is a straightforward tool that helps you quickly set up a research study. It offers a ready-to-use template for organizing your study's structure and surveys, ensuring everything meets standard guidelines. Think of it as a quick-start guide to get your research project up and running smoothly. A step-by-step guide see [here](../docs/41_create_new_protocol.md).
+The reproschema-protocol-cookiecutter is a straightforward tool that helps you quickly set up a research study. It offers a ready-to-use template for organizing your study's structure and surveys, ensuring everything meets standard guidelines. Think of it as a quick-start guide to get your research project up and running smoothly. A step-by-step guide see [here](41_create_new_protocol.md).
 
 ## Other repositories
 

docs/30_schema.md

@@ -1,5 +1,35 @@
 # The schema
 
+## Overview
+
+A simplistic way to describe the Reprochema is to say it is organized in a hierarchical manner with roughly 3 levels with a schema describing each level.
+
+1.  The highest level is the `protocol` level that originally define a set of assessments or questionnaires to be
+included in a given study.
+This schema is defined by the [Protocol schema](https://raw.githubusercontent.com/ReproNim/reproschema/master/terms/Protocol).
+1.  The second level is the `activity` level that describe a given questionnaire. This level would describe all the questions of this assessment: for example all the items of the Edinburgh handedness inventory would constitute one activity.
+This schema is defined by the [Activity schema](https://raw.githubusercontent.com/ReproNim/reproschema/master/terms/Activity).
+1.  At a lower level we have the `item` level where each `item` represents a question from a given assessment.
+On top of containing the text of the actual question, the schema at this level can contain additional
+information such as the expected format of the item for the user interface: a boolean
+(if this is a yes/no question), a multiple choice (with a list of the response choices),
+a float or an integer (if a numerical value is expected)...
+This schema is defined by the [Field schema](https://raw.githubusercontent.com/ReproNim/reproschema/master/terms/Field).
+
+<img
+src="../img/reproschema.png"
+alt="reproschema"
+style="width: 800px; height: auto; display: block; margin-left: auto;  margin-right: auto;"/>
+
+You can see an example of those in the [examples folder](https://github.com/ReproNim/reproschema/examples)
+
+There are in fact more levels than this each and each level has its own schema:
+- all of the schemas can be found in the [`terms` folder](https://github.com/ReproNim/reproschema/terms)
+- the Reproschema actually allows for a more complex level nesting than the one described above (e.g you can have an `activity` wihtin an `activity`)
+- all the properties of each level are described below in the [Properties of ReproSchema objects section](#properties-of-reproschema-objects)
+
+## Detailed description
+
 The core model of ReproSchema was initially derived from the [CEDAR Metadata Model](https://more.metadatacenter.org/tools-training/outreach/cedar-template-model).
 To accommodate the needs of neuroimaging and other clinical and behavioral
 protocols and assessments the schema has evolved significantly. These changes
@@ -29,10 +59,10 @@ common in biomedical and other domains.
         │   ...
         ...
 
-1. Interaction with git/Github or another Web service to deliver a new Protocol,
-Activity or Field with a persistent URI, while tracking changes associated with
-any of these elements. By making every Field represented through a persistent URI,
-a data collection instrument can link the responses to the exact Field that was
+1. Interaction with Git/Github or another Web service to deliver a new `protocol`,
+`ativity` or `field` with a persistent URI, while tracking changes associated with
+any of these elements. By making every `field` represented through a persistent URI,
+a data collection instrument can link the responses to the exact `field` that was
 used.
 1. Addition of computable elements that are derived from the values entered by a
 participant.

docs/50_using_reproschema.md

@@ -0,0 +1,85 @@
+# How can I use reproschema to create my own questionnaire?
+
+Broadly speaking, there are two ways to create new assessments (`actitivies`) or combinations
+of assessments (`protocols`). IF you only have very few items to put in new activity or you simply want to create a protocol that reuses activities that already exist, you can do that manually by editing the files directly. But if you have to create complex activities or protocols, we suggest that for your own sanity and to avoid wasting time in the long run, you look into scripting the creation of your new tools.
+
+## Manual schema generation
+
+Here we will show a step by step approach to create a new protocol that includes activities that already exist and how to create a brand new activity.
+
+## Requirements
+
+For this tutorial you will be using some other tools to put your work online. Here is what you will need to install or set up.
+
+- [Git](https://git-scm.com/downloads)
+- a [Github account](https://github.com/)
+- a "decent" text editor like [atom](https://atom.io/) or [visual studio code](https://code.visualstudio.com/) and we do recommend that you look for extensions or packages that help you deal with json files.
+
+We don't assume that you have in-depth knowledge of Git and Github for this tutorial so we will try to provide with the commands you need to type when it is required. Similarly, we will provide some of the commands to create directories and files though you could do many of those actions "by hand" with a couple of mouse clicks.
+
+??? "For Windows users"
+    Most of the commands we will provide should work in the command line interface that will come on your computer when you isntall Git. But you could also look into using one the linux sub-system that provide you with Unix command line and that can be easily installed from the app-store on your computer.
+
+## Context
+
+To make this a bit less abstract, we will imagine we want to create a new protocol for a new neuroimaging study we are starting to investigate some aspects of linguistic processing is affected in patients with depression.
+
+So we would want to have a set of questionnaires:
+
+- to assess the severity of the depression of our participants,
+- check which participants can go in an MRI scanner,
+- estimate the handedness of the participants (because of the language lateralization organization of the brain).
+
+
+## A note about this tutorial
+
+We will be creating several jsonld files in this tutorial. Those can quickly grow big and it can be hard to see what was added to a certain file from one step to the next. This gets even more confusing when you know that the order of the lines does not really matter. So to makes things easier to follow (and unless we explicitly say so) any new content we add to a file we have already worked on will be put at the end of this file.
+
+So if step 1 looked like this: 
+
+```json
+{
+  "@context": "some_URL",
+  "@type": "reproschema:Protocol",
+  "@id": "some_id",
+  "schemaVersion": "1.0.0",
+  "version": "0.0.1",
+}
+```
+
+We will make sure that step 2 where we add a `landingPage` field looks like this:
+
+```json
+{
+  "@context": "some_URL",
+  "@type": "reproschema:Protocol",
+  "@id": "some_id",
+  "schemaVersion": "1.0.0",
+  "version": "0.0.1",
+  "landingPage": {"@id": "README.md"}
+}
+```
+
+Although some other possibility would be equivalent:
+
+```json
+{
+  "landingPage": {"@id": "README.md"},
+  "@context": "some_URL",
+  "@type": "reproschema:Protocol",
+  "@id": "some_id",
+  "schemaVersion": "1.0.0",
+  "version": "0.0.1",
+}
+```
+
+```json
+{
+  "@context": "some_URL",
+  "@type": "reproschema:Protocol",
+  "@id": "some_id",
+  "landingPage": {"@id": "README.md"},
+  "schemaVersion": "1.0.0",
+  "version": "0.0.1",
+}
+```