Understanding Task Structure

This guide explains how behavioral tasks are structured and displayed during participant sessions. Understanding this structure helps you configure tasks effectively and write clear instructions for participants.

Overview

Every task follows a consistent structure with four types of instructions and optional practice trials. This standardized approach ensures participants have a clear, predictable experience across different task types.

Instruction Types

Tasks support four distinct instruction types, each displayed at a specific point during the task:

1. Main Instructions

What they are: The primary instructions for the task, explaining what participants will do.

When displayed: As a dedicated page before the task begins. This page includes:

• Camera preview (if recording is enabled)
• Screen share preview (if screen sharing is enabled)
• A "Start" button to begin the task

Configuration: In the study form, use the "Pre-task instructions" field (rich text editor).

Best practices:

• Explain the goal of the task
• Describe what participants will see
• Explain how to respond
• Keep instructions concise but complete

Example:

You will see color words displayed in different ink colors. Your task is to say the color of the ink, not the word itself.

For example, if you see the word "RED" written in blue ink, you should say "blue".

2. Practice Instructions

What they are: Instructions specific to the practice phase, preparing participants for practice trials.

When displayed: After main instructions, before practice trials begin. Displayed within the task area (not a dedicated page).

Configuration: In the study form, use the "Practice instructions" field.

When to use:

• When practice trials are enabled (optional or mandatory)
• To explain that this is a practice round
• To describe the feedback that will be shown

Example:

Let's practice! You'll see a few example trials to help you get familiar with the task.

After each response, you'll see whether you were correct (✓) or incorrect (✗).

3. Trials Instructions

What they are: Instructions shown before the main (scored) trials begin.

When displayed: After practice trials complete, before main trials start. Displayed within the task area.

Configuration: In the study form, use the "Trials instructions" field.

When to use:

• When transitioning from practice to scored trials
• To remind participants that feedback will no longer be shown
• To indicate that responses now count

Example:

Practice complete! Now you'll begin the actual task.

Respond as quickly and accurately as you can. You won't see feedback after each trial.

4. Hint Instructions

What they are: Quick-reference help text available during the task.

When displayed: As a tooltip when hovering over the ? button in the top-right corner of the task area. Available throughout the task.

Configuration: In the study form, use the "During-task hint" field.

Best practices:

• Keep it brief (1-3 sentences)
• Summarize the key response rules
• Remind which buttons/keys to use

Example:

Say the color of the ink, not the word.

Task Flow Diagram

Here's how a typical task with practice trials flows:

┌───────────────────────────────────────────────────┐
│  MAIN INSTRUCTIONS PAGE                           │
│  ┌─────────────────────────────────────────────┐  │
│  │ Camera Preview  │  Screen Share Preview     │  │
│  └─────────────────────────────────────────────┘  │
│                                                   │
│  [Your main instructions here]                    │
│                                                   │
│               [ Start ]                           │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  PRACTICE INSTRUCTIONS                            │
│  (if practice is enabled)                         │
│                                                   │
│  [Your practice instructions here]                │
│                                                   │
│               [ Start Practice ]                  │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  PRACTICE TRIALS                          [?]     │
│                                                   │
│  • Stimulus displayed                             │
│  • Participant responds                           │
│  • Feedback shown (✓ or ✗)                        │
│  • Repeat for each practice trial                 │
│                                                   │
│  [Skip Practice] (if practice is optional)        │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  TRIALS INSTRUCTIONS                              │
│  (shown after practice completes)                 │
│                                                   │
│  [Your trials instructions here]                  │
│                                                   │
│               [ Start ]                           │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  MAIN TRIALS                              [?]     │
│                                                   │
│  • Stimulus displayed                             │
│  • Participant responds                           │
│  • No feedback shown                              │
│  • Repeat for each trial                          │
│                                                   │
└───────────────────────────────────────────────────┘
                      │
                      ▼
              Task Complete

Practice Trials

Practice trials help participants learn the task before their responses are scored.

Practice Modes

Mode	Description
None	No practice trials. Task starts directly with main trials.
Optional	Practice trials are available. Participant can skip practice at any time.
Mandatory	Practice trials must be completed before main trials begin.

Practice Features

• Immediate feedback: After each practice response, participants see whether they were correct (green checkmark) or incorrect (red X).
• Skip option: In optional mode, a "Skip Practice" button allows participants to move directly to main trials.
• Accuracy requirements: Some tasks may require minimum accuracy in practice before proceeding (configurable per task).

Configuring Practice Trials

In the study form task configuration:

1. Enable practice: Check "Enable practice trials"
2. Practice mode: Select "Optional" or "Mandatory"
3. Practice trials: Configure the practice trial list (similar to main trials)
4. Practice instructions: Write instructions specific to the practice phase

Button Behavior

Standard Buttons

All tasks use consistent button styling:

Button	Purpose	When Visible
Start	Begin task or phase	Before task starts, before practice, before main trials
Next	Advance to next item	During self-paced tasks
Submit	Submit a response	For tasks requiring explicit submission
Skip Practice	Exit practice early	During optional practice
? (Hint)	Show hint instructions	Always visible during task

Moderation Modes

Button visibility depends on the moderation mode:

Button	Unmoderated	Moderated	Strictly Moderated
Start	✓ Visible	✓ Visible	Hidden (moderator controls)
Next	✓ Visible	✓ Visible	Hidden (moderator controls)
Submit	✓ Visible	✓ Visible	Hidden (moderator controls)
Skip	✓ Visible	✓ Visible	Hidden (moderator controls)
Hint (?)	✓ Visible	✓ Visible	✓ Visible

In strictly moderated mode, the moderator controls task progression through the moderation dashboard.

Customizing Button Text

You can customize button labels in the study's UI translation settings:

• Start: Used for all "Start" buttons
• Next: Used for all "Next" buttons
• Submit: Used for all "Submit" buttons
• Skip: Used for "Skip Practice" buttons
• Show help: Aria label for the hint button (for accessibility)

The Hint Button

The hint button (?) appears in the top-right corner during task execution:

• Hover: Shows hint instructions as a tooltip
• Click: On touch devices, toggles the tooltip
• Content: Displays what you entered in "During-task hint"

Design tip: Keep hint content brief. It's meant as a quick reminder, not full instructions.

Tasks Without Practice

For tasks without practice trials, the flow simplifies to:

Main Instructions → Main Trials → Task Complete

The practice instructions and trials instructions fields are not used when practice is disabled.

Best Practices

Writing Effective Instructions

1. Main instructions: Be complete but concise. Explain the goal, stimuli, and response method.

2. Practice instructions: Keep brief. Mention this is practice and describe feedback.

3. Trials instructions: Short transition message. Note that feedback stops.

4. Hint instructions: One or two sentences maximum. Core response rules only.

Testing Your Instructions

Use the Preview feature in the study form to:

• Read through all instruction screens
• Check timing and flow
• Verify hint content appears correctly
• Test practice trial behavior

Common Mistakes

• Too much detail in hints: Hints should be quick reminders, not full instructions
• Missing transition instructions: If using practice, include trials instructions
• Inconsistent terminology: Use the same words across all instruction types
• No practice when needed: Complex tasks benefit from practice trials

Technical Notes

Instruction Parameters

All tasks use these standardized parameter names:

Instruction Type	Parameter Name	Description
Main	main_instructions	Pre-task instructions on dedicated page
Practice	practice_instructions	Instructions before practice trials
Trials	trials_instructions	Instructions before main/scored trials
Hint	hint_instructions	Quick-reference help via "?" button

Practice Configuration

Parameter	Type	Default	Description
practice_mode	'none' | 'optional' | 'mandatory'	'none'	Practice trial mode
practice_trials	array	[]	List of practice trial definitions
practice_instructions	string (HTML)	''	Instructions before practice
practice_feedback_enabled	boolean	true	Show feedback during practice
practice_feedback_duration_ms	number	1000	Feedback display duration