Merge pull request #1268 from BLSQ/doc_test

DOC - hierarchy from menu improvements

docs/index.md

@@ -1,4 +1,6 @@
-## Welcome to the documentation of IASO
+# Welcome to the documentation of IASO
+
+## Introduction to IASO
 
 IASO is an innovative, open-source, bilingual (EN/FR) data collection platform with advanced geospatial features to plan, monitor and evaluate health, environmental or social programmes in low- and middle-income settings (LMICs). IASO is recognized as a Digital Public Good by the Digital Public Good Alliance and listed as a Digital Square Software Global Good, a testament to its proven impact.
 
@@ -7,7 +9,8 @@ IASO comprises:
 - a **web dashboard** - intended for supervisors to organize data collection and geographical data management
 - a **mobile application** that also works **offline** - intended to field users to fill out forms and send data when network is available
 - a **matching and scripting interface** to analyze, compare and merge several geographic data sources
-- a bi-directional **integration with DHIS2**, the widely used HMIS in LMICs
+- a bi-directional **integration with DHIS2**, the widely used Health Management Information System in Low- and middle-income countries
+
 
 In terms of features, IASO can be summarized around **three main components** which are interconnected and expand the powers of one another:
 
@@ -38,4 +41,4 @@ IASO is made of a white labeled Android application using Java/Kotlin, reusing l
 
 The companion mobile app for Android allow submitting forms and creating org unit.
 
-Forms can also be filled in a web interface via the Enketo companion service. Both Iaso and Enketo need to be configured to work together. It is possible to run an Enketo service locally.
+Forms can also be filled in a web interface via the Enketo companion service. Both IASO and Enketo need to be configured to work together. It is possible to run an Enketo service locally.

docs/pages/users/reference/iaso_concepts/iaso_concepts.md

@@ -0,0 +1,45 @@
+# Concepts
+
+## Questionnaires or XLS data collection forms
+
+What comes with data collection are questions, and to organize these questions, **data collection forms**. These are basically lists of the questions one would like to collect answers for, while specifying options (mandatory or not, skip a question depending on previous answer, etc.).
+IASO builds on [XLS forms](https://xlsform.org/en/) for its questionnaires, which are therefore pre-defined using an Excel file.
+
+In IASO, data collection forms are **versioned** meaning that every time a new version is created, the former version is kept and available in the system. 
+
+## Organization Units
+IASO uses the notion of **Organization Units (Org unit or OU)** to manage geographic data. 
+The **organisation unit types (OUT)** represent levels in the hierarchy
+
+Example:
+
+- Country
+
+- Region
+- District
+- Area
+- Facility/Village/Point of Interest
+
+The organization units are classified in the pyramid according to a parent and one or several children (except the top parent(s) and the lowest child/children). 
+Example below:
+
+- Democratic Republic of Congo (Org unit type "Country") is the parent org unit of
+
+- Kinshasa (Org unit type "City"), which is the parent org unit of 
+- Bluesquare office (Org unit type "Office")
+
+
+Data collection in IASO is structured according to the defined hierarchy, and any user needs to explicitly select an organization unit before proceeding to opening the questionnaire and answer questions. This way, one makes sure that the data collected is correctly associated with the relevant geography. 
+
+## Projects
+In IASO, a Project is a mobile application instance, with its own App ID. Within one account, you can have one or several Project(s) with different feature option(s). 
+Users can be linked to one or several Project(s). 
+
+Good to know:
+
+- One Project is linked one data source
+
+- One Project  can be linked to one or several users
+- Some users can be limited to one or several Project(s)/App ID(s) - you can define this in the User management part
+- Every Org Unit Type has to be linked to one or several Project(s)
+- Every Form has to be linked to one or several Project(s)

docs/pages/users/reference/iaso_mobile/iaso_mobile.md

@@ -0,0 +1,64 @@
+# Mobile Application
+
+IASO mobile application is available on Google Play Store (Android phones only).
+
+It can work completely offline - once the end user has encoded the data needed, he/she can upload the data collected offline all at once when network is available.
+
+Updates made from the web (forms versions, health pyramid) will be reflected in the App only **after the App data has been refreshed** and this requires network connectivity.
+
+Key tip before testing / using the App - **Make sure you have refreshed data beforehand**
+
+## Run the mobile application for the first time
+
+IASO Mobile application has to be configured on the web part before using (see the part “Project”).
+
+Then you can:
+
+- Download [IASO App](https://play.google.com/store/apps/details?id=com.bluesquarehub.iaso&pcampaignid=web_share) on Google Play
+
+- Insert the server url : https://iaso.bluesquare.org
+- Then, enter the App ID 
+
+
+
+![](attachments/iasomobileapplicationsetup.png)
+
+
+## Overview of buttons
+
+See below an overview of the main buttons that you can find on the main screen in data collection mode. 
+
+![](attachments/mobileappbuttons.png)
+
+In the More Options part, you can take the below actions:
+- Refresh data: you need to have internet connectivity to do so. It will synchronize the mobile application with IASO web data. In order to avoid that it takes too long in low-connectivity settings, you can choose to refresh only sub-parts such as Forms, Organization Units, or other. 
+- Change the App ID: you can switch Project by entering another App ID. In order to make sure that there is no data from the former App ID left on the IASO mobile application, please access your parameters and erase storage and cache data from IASO beforehand. 
+- Change the URL of the server: this can be handy if you need to switch from Production to Staging server
+- Logout: your user can logout. This does not prevent data consultation of local data (data available on IASO on the user's device)
+- About: gives the version of the IASO mobile application. It can be good to have to debug.
+
+## Collect data
+
+Once you are connected to the IASO mobile application, you can then proceed with your data collection. Here below are the different screens that you would see for a simple data collection.
+
+![alt text](attachments/datacollection.png)
+
+You will then have data collection form chosen opening. You can proceed with answering the different questions and press "Next" until the end of the Form.
+
+If you wish to interrupt data collection during input, you can press the back button on the tablet or smartphone.
+
+Once you click on the button, you have 2 options:
+- Save Changes: to save all data already filled and the form with unfinalized status. With this option you can, come back and continue enter data 
+- Ignore Changes: to delete data filled and the form
+
+**Upload collected data**
+
+If you collect data with your mobile device, they are stored in your device. You need to upload data to the server to make them visible at central level. *Keep in mind that you need internet connection in order to be able to upload data*.
+
+Click on the "Send Finalized Forms" icon on the mobile application home page on the top right corner.
+
+![alt text](attachments/uploaddata.png)
+
+Then, a specific page will open to let you know if the data has been correctly uploaded. Finalize the operation by clicking on "Send to server".
+
+![alt text](attachments/sendserver.png)

docs/pages/users/reference/iaso_modules/iaso_modules.md

@@ -0,0 +1,31 @@
+# Modules
+
+IASO is organized according to Modules, which are groups of functionalities which can be added up depending on the use case to cover. Here are the Modules available in IASO:
+
+## Data collection functionalities
+- Manage data collection forms (XLS forms) and their related data submissions
+- Manage geographic data (import/export of geo data from Excel, DHIS2 or Geopackages, manage the Organizations Units and their hierarchy)
+- Monitor the data collection process with the completeness statistics table and map
+- Manage users and their permissions and geographies, user roles and teams
+- Create mobile application(s) IDs and manage related features options
+
+## Georegistry 
+- Import several data sources from Excel, DHIS2 or Geopackages, compare and merge them as needed
+- Visualize on a dynamic map data collected at the different levels of the hierarchy (e.g. Country, Region, District, facility)
+- Validate changes on Organization Units (Name, Type, GPS coordinates, opening/closing dates) submitted from the field via the mobile application
+- Validate data submitted via data collection forms that are linked to specific Organization Units types, called "Reference forms"
+- Based on the validated proposed changes per user, generate payment lots to send to Mobile Money provider
+
+## DHIS2 bi-directional integration 
+- Manage the mappings with DHIS2 data elements for import/export of data
+
+## Planning
+-  Plan ahead your data collection activities by creating a planning with a set timeframe, geography, data collection forms and teams
+- Assign data collection tasks to teams and users from the map-based interface available on the web
+- Once tasks have been assigned, the mobile application users on the field will only see the forms that have been assigned to them
+
+## Entities
+- Entities are items that can move from a geography to another, for instance a person, a pallet of goods, or other
+- Entities can be created from the mobile application and then managed from the web application
+- Find the entities duplicates by using the web application interface and make the decision to merge two similar entities or not
+- Assign workflows to entity types, enabling specific data collection forms to open according to previsouly given answers