122 propose structure for a user manual

README.md

@@ -8,21 +8,30 @@ This repository aims at providing a **vendor-neutral**, **fact-based**, **non-ju
 
 - [🗺️ Mapping of the ICT Sustainability Tools Landscape](#️-mapping-of-the-ict-sustainability-tools-landscape)
   - [Getting started 🚀: visualize the data](#getting-started--visualize-the-data)
-  - [Raw data (CSV)](#raw-data-csv)
-  - [Data model](#data-model)
-  - [Documentation](#documentation)
+  - [User manual](#user-manual)
+  - [Technical details](#technical-details)
+    - [Raw data (CSV)](#raw-data-csv)
+    - [Data model](#data-model)
+    - [Documentation](#documentation)
   - [Acknowledgments](#acknowledgments)
   - [Licenses](#licenses)
 
 ## Getting started 🚀: visualize the data
 
 Visualize or edit the data set at [https://boavizta.github.io/ict-sustainability-tools/](https://boavizta.github.io/ict-sustainability-tools/)
 
-## Raw data (CSV)
+## User manual
+
+Check [how to use the tool](/doc/user-manual/how-to-use-the-tool.md).
+
+
+## Technical details
+
+### Raw data (CSV)
 
 See the [CSV dataset](ictst/data/tools.csv)
 
-## Data model
+### Data model
 
 This repository proposes a common data model that is used to reference all the tools or services.
 
@@ -31,7 +40,7 @@ The [data model](ictst/model/tools.frictionless-table-schema.json) of the raw da
 > [!WARNING]
 > The data model is still very drafty and is expected to evolve.
 
-## Documentation
+### Documentation
 
 See [/doc/technical-documentation.md](/doc/technical-documentation.md)
 

doc/user-manual/how-to-something-else.md

@@ -0,0 +1,3 @@
+# A second page
+
+With detailed instructions.

doc/user-manual/how-to-use-the-tool.md

@@ -0,0 +1,19 @@
+# How to use this tool
+
+## Visualizing the data 
+
+> 💡 TODO: describe here how the interface works, possibility to see table or cards view, filtering capabilities.
+
+![Sample picture with alt text](picts/sample-pict.excalidraw.png)
+
+## Contributing to the data
+
+### The general contribution process
+
+> 💡 TODO: Describe here how contribution are managed / reviewed
+
+### How to edit the data
+
+## Other info
+
+See also this [next chapter](how-to-something-else.md).

ictst/texts/README.md → ictst/texts/about.md

@@ -19,6 +19,8 @@ Please get in touch or contribute (see below) if you notice errors in the data.
 
 ## Next step
 
+Have a look at the [user manual](https://github.com/Boavizta/ict-sustainability-tools/doc/user-manual/how-to-use-the-tool.md).
+
 Open the [next tab](https://boavizta.github.io/ict-sustainability-tools/?datami_tab=2&datami_view=cards) to visualize the dataset.
 
 ## Get in touch
@@ -32,3 +34,5 @@ To propose an update on the data set, you have 2 options:
 The easiest way to contribute is to use the *EDIT* button on the next tab to propose a update. It will appear as an anonymous contribution to be validated in the git repository of the project.
 
 If you are familiar with git and csv editing, you may propose contributions directly as PR on the git repository.
+
+All details are given in the [user manual](https://github.com/Boavizta/ict-sustainability-tools/doc/user-manual/how-to-use-the-tool.md).

index.html

@@ -36,8 +36,8 @@
         "activate": true,
         "default-tab": false,
         "localdev": false,
-        "gitfilelocal": "http://localhost:8800/statics/ictst/texts/README.md",
-        "gitfile": "https://github.com/Boavizta/ict-sustainability-tools/blob/main/ictst/texts/README.md",
+        "gitfilelocal": "http://localhost:8800/statics/ictst/texts/about.md",
+        "gitfile": "https://github.com/Boavizta/ict-sustainability-tools/blob/main/ictst/texts/about.md",
         "onlypreview": true,
         "usertoken": ""
       },