Adding New Vignettes and Smokescreens

This guide explains how to add new vignettes or smokescreens to the Novaland experiment.

Folder structure

The HTML files that define the visual layout of vignettes and smokescreens are stored in the following locations:

  • main/vignettes/ — contains the HTML files for each vignette (e.g., doctor.html, passport.html)

  • main/smokescreens/ — contains HTML files for smokescreen pages

Each vignette or smokescreen corresponds to a real-life public service scenario.

Steps to add a new vignette

  1. Create the HTML file

    Create a new HTML file and save it in main/vignettes/, for example:

    ` main/vignettes/hospital.html `

  2. Update constants in `main/__init__.py`

    Add the name of your new vignette to the vignettes list and decide in which round(s) it should appear.

    Example:

    ```python class C(BaseConstants):

    … VIGNETTE_ROUNDS = [3, 4, 6, 7] vignettes = [‘doctor’, ‘handyman’, ‘kindergarten’, ‘passport’, ‘hospital’]

    ```

  3. Edit `vignette_q.yaml`

    This YAML file, located in data/vignette_q.yaml, defines the survey questions shown after the vignette page.

    Example excerpt from vignette_q.yaml:

    ```yaml - name: satisfaction_page

    elements:

    • type: radiogroup name: satisfaction_service title: Bitte bewerten Sie die Qualität der Dienstleistung. choices:

      • value: 1 text: “1 Sehr gut”

      …

    ```

    Conditional logic can be used to include or skip certain blocks depending on the context (e.g., if the vignette is corrupt).

  4. Edit `corrupt_endings.yaml`

    If your vignette has a corrupt version with an alternative ending, add the corresponding text to corrupt_endings.yaml located in the same data/ folder.

    Example structure:

    ```yaml hospital: >

    Der Arzt verweigert die Behandlung, bis Sie eine informelle Zahlung leisten.

    ```

  5. Optional: Add smokescreen pages

    If you want to include a smokescreen (a filler or distractor vignette), follow the same steps as for vignettes, but place the HTML file in main/smokescreens/ and include the round number in SMOKESCREEN_ROUNDS.

    Example:

    `python SMOKESCREEN_ROUNDS = [1, 5] `

Checklist

  • [ ] HTML file added to the correct folder

  • [ ] Name added to C.vignettes

  • [ ] Round(s) added to VIGNETTE_ROUNDS or SMOKESCREEN_ROUNDS

  • [ ] YAML files updated with relevant questions and endings