From bc43d70196c42b9fd309c945a36f9ee3ecc860a8 Mon Sep 17 00:00:00 2001
From: Brieuc Dubois <git@bhasher.com>
Date: Sun, 12 Jan 2025 11:20:07 +0100
Subject: [PATCH] Implement #84 todo

---
 scripts/surveys/README.md | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/scripts/surveys/README.md b/scripts/surveys/README.md
index 1066a07b..f58b7adc 100644
--- a/scripts/surveys/README.md
+++ b/scripts/surveys/README.md
@@ -10,11 +10,43 @@ The data required to create surveys is divided into three CSV files:
 2. `groups.csv` to create groups, where items are just appended at the end of each line.
 3. `surveys.csv` to create surveys, where groups are appended at the end of each line.
 
-Even if the script do some checks, it's important to double-check that there is no duplicates in ID for each field, or it will fail (or not provide the expected output). 
+Even if the script do some checks, it's important to double-check that there are no duplicates in ID for each field, or it will fail (or not provide the expected output). 
 It's also important to know that running again a script on the same survey/group/item, will first **delete** it, before recreating it. So, be cautious!
 
+### Format
+
+The CSV is formatted as follows:
+```csv
+id,question,correct,option1,option2,option3,option4,option5,option6,option7,option8
+```
+
+Unused options can be let blank. Example:
+```csv
+1,"What's your favorite color?",1,"Red","Blue","Green",,,,,
+```
+
 In `items.csv`, blanks fields are replaced by files from [static/surveys/items](../../frontend/static/surveys/items), with the structure `<item_id>/<option_id|q>.<jpeg|mp3>`. 
 
+The previous example could become:
+```csv
+1,"What's your favorite color?",1,,,,,,,,
+```
+with
+```sh
+/static/surveys/items/1/1.jpeg  # Red picture
+/static/surveys/items/1/2.jpeg  # Blue picture
+/static/surveys/items/1/3.jpeg  # Green picture
+```
+
+### Types
+
+Each value can have 4 types:
+- Text: `"What's your favorite color?"`
+- Image: `<blank>` with `/static/surveys/item/<item_id>/<option_id>.jpeg`
+- Sound: `<blank>` with `/static/surveys/item/<item_id>/<option_id>.mp3`
+- Gapfill: `What's y<ou>r (ta) favourite c<olo>r (couleur)?` (only on questions, responses entries are ignored)
+
+
 ### Sample questions
 
 In `groups.csv` there is a column `demo` that need to be set to `true` or `false`.
-- 
GitLab