update admin documentation

backend/docs/03_The_admin_interface.md

@@ -12,7 +12,7 @@ Log in:
 (This is set through the .env file. Obviously, these passwords are only suitable for local development!)
 
 You can see an overview of different Django apps:
-<img width="656" alt="adminList" src="/assets/images/AdminInterface.png">
+<img width="656" alt="adminList" src="/assets/images/admin/AdminInterface.png">
 
 - **Admin_Interface** to customize how this admin interface appears to you
 - **Authentication and Authorization** to give other researchers access to this admin interface

backend/docs/05_Creating_an_experiment.md

@@ -4,21 +4,38 @@
 Make sure you're logged in to the admin interface (see previous step).
 
 Then, next to "Experiments" click "Add".
-<img width="1002" alt="AddExperiment" src="https://github.com/Amsterdam-Music-Lab/MUSCLE/assets/11174072/f71e77a1-1308-40f3-b8d5-e6f81f2ae0c0">
+<img alt="AddExperiment" src="/assets/images/experiments/AddExperiment.png">
 
 ## The Experiment form
 The form which appears lets you select the following fields:
-1. a name for your new experiment (required)
-2. a slug for the experiment (required). The slug is the part of the part of the URL which will be used to find the experiment from the frontend. In this case, the experiment will be available from `localhost:3000/someslug`.
-3. a URL with more information about the experiment (optional)
-4. a hashtag for posting about the experiment on social media (optional)
-5. a preferred language in which the experiment should be shown (optional). If this field is left "Unset", this means that the language will be determined based on the user's browser settings. Otherwise, the set language will be shown, with a fallback to English in case no translation is available.
-6. the rules of the experiment (required). This sets which logic the experiment follows. You can select implemented "rules" that have already been implemented in Python.
-7. the number of rounds the experiment should run (optional). This is set to 10 by default, which is usually fine. Not all rules files use rounds to control when specific "phases" of the experiment start or end. Think of staircasing experiments, which will present more or less difficult stimuli depending on the user's responses. These rules just ignore the "Rounds" field.
-8. bonus points (optional). Few experiments use this field, but you can use this to give bonus points to a participant who completed the experiment.
-9. a playlist (optional). For most experiments (except for those which are questionnaires) you will want to select a playlist here.
-<img width="828" alt="AddExperimentPart1" src="https://github.com/Amsterdam-Music-Lab/MUSCLE/assets/11174072/97d57e23-aa26-40db-83ec-a1312873fdf4">
-
-10. an experiment series (optional). This is used to string several experiments together. Best to leave alone, may be deprecated.
-11. questions (optional). You can select any questions you want to ask your participants before starting an audio experiment here.
-<img width="992" alt="AddExperimentPart2" src="https://github.com/Amsterdam-Music-Lab/MUSCLE/assets/11174072/d8253af5-9be2-4428-a90a-9e612c863fb8">
+
+1. a unique slug for your new experiment (required) If you test locally, the experiment will be available from `localhost:3000/someslug`.
+
+2. a checkbox indicating whether the experiment is active
+
+3. optional: a theme config (through which you can change the background, logos, etc.)
+
+4. `Translated Content` containing information about the experiment, a consent file, and messages to be displayed on social media, in a given language.
+
+5. Phases (required): a phase of your experiment, which may contain one or more blocks. Note that every experiment needs to have at least one phase with one block configured.
+
+    If you select "dashboard", the phase will appear as a dashboard, from which users can select which block to play. If "dashboard" is false, the blocks will be presented in linear order to the participant. If you select "randomize", the blocks will be shuffled, either in the dashboard view, or the linear procedure.
+
+    Within a phase, you have the option to add one or more **blocks**, with the following options:
+
+    - Index: order in which block should appear in the phase (will be ignored when `phase.randomize` is set)
+
+    - Slug: unique slug of the block
+
+    - Rules: the ruleset for the block
+
+    - Rounds: how many rounds should be presented to the participant (*used in some, but not all rulesets!*)
+
+    - Bonus points: bonus points to be awarded to the participant under given conditions (*used by very few rulesets*)
+
+    - Playlists: select one or more playlists to be associated with the block (*note that some rulesets require a very specific format for the playlist, this will be checked when you save the experiment, and may generate warnings*)
+
+    - BlockTranslatedContent: a name and description of the block in a given language, will only be shown in the dashboard view
+
+6. a Social Media Config to customize the tags and url which should be shown when participants share that they played the experiment on social media, as well as the channels in which they can share
+

backend/docs/06_Custom_questions.md

@@ -1,54 +1,60 @@
 # Custom questions
+You can add questions to the MUSCLE infrastructure through the admin interface.
 
-## The backend directory
-To add questions that haven't yet been added to the MUSCLE infrastructure, you'll have to navigate to the backend directory. It has the following file structure:
-```bash
-.
-├── aml
-├── experiment
-├── locale
-├── logs
-├── participant
-├── requirements
-├── requirements.in
-├── result
-├── section
-├── session
-└── upload
-```
-
-The backend is written in Python, so a little bit of familiarity with programming is required. Within the backend directory, go to the `experiment` directory. Within, you find the following file structure:
-```bash
-.
-├── actions
-├── fixtures
-├── management
-├── migrations
-├── questions
-├── rules
-├── standards
-├── templates
-└── tests
-```
-
-The files in the `rules` directory specify the logic of experiments. We'll turn to those later.
-
-The files in the `questions` directory contain the questions, as Python classes. For instance, if you look into the file `goldsmiths.py` you'll see the following:
-<img width="720" alt="Screenshot 2023-11-14 at 14 30 51" src="https://github.com/Amsterdam-Music-Lab/MUSCLE/assets/11174072/723f1add-602c-4e34-ae01-4b683af56157">
-
-We have different question types available, all imported from `backend/experiment/actions/forms.py`:
-- NumberQuestion (number field)
-- TextQuestion (text field)
-- BooleanQuestion (yes/no buttons)
-- ButtonArrayQuestion (more than 2 buttons)
-- RadiosQuestion (radio buttons)
-- DropdownQuestion (dropdown menu)
-- AutoCompleteQuestion (dropdown menu with autocomplete)
-- RangeQuestion (slider)
-- LikertQuestion (slider in which chosen category is displayed on top)
-
-As you can see, the Goldsmith's Musical Sophistication Index uses many LikertQuestions. LikertQuestions can be initialized with a `key` and a `question` argument. The key helps us find the responses to the question back in the database, so it's a good idea to use a unique, recognizable key. The key should not contain other characters than numbers, letters and underscores.
-
-The `question` is the prompt shown to a participant. Here, it is wrapped in a translation tag (represented by `_( )`): this means the question can be translated into different languages.
-
-If you wish to add questions to the infrastructure, you are of course welcome to so in a fork of the project. However, if you think the questions may be of interest to other users, consider making a [git branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) and contribute to this repository with a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+In the admin overview, you can see the question app with three models:
+<img width="656" alt="adminList" src="/assets/images/questions/QuestionApp.png">
+
+## Question Groups
+Question Groups are sets of questions which are predefined, such as "Demographics" or question sets from the Goldsmith MSI questionnaire. We recommend not editing these, but you can add your own Question Group if you want to reuse the same set of questions in multiple experiments.
+<img width="500" alt="adminList" src="/assets/images/questions/QuestionGroup.png">
+
+## Question Series
+Question Series are sets of questions you can attach to a given block in your experiment. If you click "Add", you will see the following form:
+<img alt="adminList" src="/assets/images/questions/QuestionSeries.png">
+
+You need to give the Question Series a descriptive name, and choose the block with which it is associated (important: the block will only display questions if its ruleset has a method that presents these questions to the participant), and an index, used for handling order if you have multiple `QuestionSeries` attached to a given block.
+
+You can also choose whether or not the questions in the Question Series should be presented in randomized order.
+
+To add questions to the Question Series, you can either select from a list of questions, or add all questions from a Question Group. You can then remove or add other questions as you wish.
+
+## Questions
+Questions are the actual question objects. Many questions are already configured. If you click "Add", you will see the following form:
+<img alt="adminList" src="/assets/images/questions/Question.png">
+
+On the top, you can choose the language(s) in which you wish to enter the question. The languages that are shown can be configured through the `MODELTRANSLATION_LANGUAGES` settings in Django. Note that it is not necessary to provide translations, but that a question will be much more reusable if it has translations to multiple languages.
+
+Enter a descriptive question key, e.g., `favorite_food_open_question`. Note that the key can only contain letters, numbers, and underscores.
+
+The Question is the actual question text that will be asked to the participant. Optionally, you can also add an Explainer with instructions to the participant, e.g., "Rate on a scale of 1 to 7".
+
+Indicate the *Type* of question, which influences the widget participants will see:
+
+- AutoCompleteQuestion will show a dropdown which will autocomplete if a participant starts typing
+
+- BooleanQuestion will show yes/no buttons
+
+- ChoiceQuestion will show a select menu (can be further configured as radio / dropdown etc.)
+
+- LikertQuestion will show a slider with different answer options
+
+- LikertQuestionIcon will show icons instead of text for different answer options
+
+- NumberQuestion will show a number selector
+
+- TextQuestion will show a text field - use this for open questions
+
+Finally, you can indicate whether your question can be skipped by the participant.
+
+Clicking "Save and continue editing" on all questions but `TextQuestion` will bring up another menu:
+<img alt="adminList" src="/assets/images/questions/QuestionChoice.png">
+
+You can select different widgets:
+- BUTTON_ARRAY: a horizontal array of buttons with the answer options (one answer possible)
+- CHECKBOXES: a vertical array of checkboxes (multiple answers possible)
+- DROPDOWN: a dropdown menu (one answer possible)
+- RADIOS: a vertical array of radio buttons (one answer possible)
+
+For CHECKBOXES, you also need to indicate how many answers need to be minimally checked before the participant can click the "submit" button
+
+Finally, you can add Choices, which are again a combination of a descriptive key (consisting of letters, numbers, and underscores), and a translatable text. The index controls the order in which choices will appear.