Instructions Task

Version: v1 (current)

A content display task for presenting study information, consent forms, instructions, or educational materials to participants.

Overview

The Instructions task is a versatile content presentation component that displays rich-text information to participants during a study. Unlike behavioral tasks that measure responses, this task simply presents content and waits for the participant to indicate they've read and understood it before proceeding.

This task is essential for:

• Study introductions: Welcome messages and study overview
• Informed consent: Displaying consent information (though formal consent should use dedicated consent forms)
• Task instructions: Detailed instructions before complex tasks
• Debriefing: Post-study information and explanations
• Educational content: Teaching materials in intervention studies
• Break screens: Rest periods between demanding tasks

The task supports rich HTML formatting, images, videos, and external links, making it suitable for sophisticated content presentation needs.

Why Researchers Use This Task

1. Study Flow Control: Structure the study with informational phases
2. Participant Preparation: Ensure participants understand what's coming next
3. Standardization: Deliver identical information to all participants
4. Documentation: Create audit trail of what participants were shown
5. Flexibility: Present any content needed for the study design
6. Multi-Page Instructions: Break complex instructions into digestible sections

Current Implementation Status

Fully Implemented:

• ✅ Rich HTML content display (formatting, images, links)
• ✅ Embedded video and audio support
• ✅ Multi-page instruction sequences
• ✅ Configurable advancement button text
• ✅ Time-on-page logging
• ✅ Scroll tracking (ensures participant scrolled to bottom)

Partially Implemented:

• ⚠️ Limited interactive elements (no quizzes or comprehension checks)

Not Yet Implemented:

• ❌ Mandatory minimum viewing time before advancing
• ❌ Comprehension check questions
• ❌ Audio narration option (text-to-speech)

Configuration Parameters

Content Parameters

Parameter	Type	Default	Description
Content	string (HTML)	''	Main content to display (rich HTML)
Pages	array	[]	Multiple pages of content (array of HTML strings)
Title	string	''	Optional title displayed above content

Presentation Parameters

Parameter	Type	Default	Description
Show Progress	boolean	false	Show "Page X of Y" for multi-page content
Require Scroll To Bottom	boolean	false	Require scrolling to bottom before "Next" enabled
Button Text	string	'Continue'	Text for advancement button
Button Delay (ms)	number	0	Delay before button becomes active (0 = immediate)

Styling Parameters

Parameter	Type	Default	Description
Font Size (px)	number	16	Base font size for content
Max Width (px)	number	800	Maximum width of content area
Text Align	string	'left'	Text alignment ('left', 'center', 'justify')

Data Output

Markers and Responses

Markers (response_recorded):

{
  "type": "response_recorded",
  "ts": "2024-01-01T00:00:13.450Z",
  "hr": 13684.56
}

Response Data (when file upload is disabled):

{
  "event": "instructions_complete",
  "files_uploaded": 0,
  "total_size_mb": 0,
  "files": []
}

When file upload is enabled, additional responses are recorded for each file action:

File uploaded:

{
  "event": "file_uploaded",
  "file_id": "abc123",
  "file_name": "document.pdf",
  "file_size": 204800,
  "file_type": "application/pdf",
  "filename": "task_0_abc123_document.pdf"
}

File removed:

{
  "event": "file_removed",
  "file_id": "abc123",
  "file_name": "document.pdf"
}

File upload error:

{
  "event": "file_upload_error",
  "error": "file_too_large"
}

Possible error codes: "max_files_exceeded", "file_too_large", "total_size_exceeded", "invalid_file_type", "upload_failed".

Summary Artifact

None. The instructions task does not generate a summary artifact.

Example Use Cases

Study Welcome Screen

<h2>Welcome to the Cognitive Assessment Study</h2>
<p>Thank you for participating! This study will take approximately 30 minutes.</p>
<p>You will complete several brief cognitive tasks measuring attention, memory, and decision-making.</p>
<p>Please ensure you are in a quiet environment and will not be interrupted.</p>
<p>Click "Begin" when you are ready to start.</p>

Configuration:

{
  "content": "<h2>Welcome...</h2>...",
  "button_text": "Begin",
  "text_align": "center"
}

Multi-Page Task Instructions

pages: [
  "<h3>Instructions - Part 1</h3><p>In this task, you will see words displayed one at a time...</p>",
  "<h3>Instructions - Part 2</h3><p>For each word, you must decide if it names a living thing...</p>",
  "<h3>Instructions - Part 3</h3><p>You will have 10 practice trials with feedback...</p>"
]

Configuration:

{
  "pages": ["page1 html", "page2 html", "page3 html"],
  "show_progress": true,
  "button_text": "Next",
  "require_scroll_to_bottom": true
}

Debriefing Screen

<h2>Study Complete - Thank You!</h2>
<p>The tasks you completed help researchers understand cognitive processing.</p>

<h3>What We Measured</h3>
<ul>
  <li><strong>Attention</strong>: Your ability to focus and filter distractions</li>
  <li><strong>Memory</strong>: How you encode and retrieve information</li>
  <li><strong>Processing Speed</strong>: How quickly you process information</li>
</ul>

<h3>Your Data</h3>
<p>Your responses are confidential and will only be used for research purposes...</p>

<p>If you have questions, please contact: researcher@university.edu</p>

Configuration:

{
  "content": "<h2>Study Complete...</h2>...",
  "button_text": "Finish",
  "button_delay_ms": 3000
}

Consent Information (Informational Only)

<h2>Study Information</h2>
<p><strong>Purpose:</strong> This study investigates cognitive aging...</p>
<p><strong>Procedures:</strong> You will complete computerized tasks (30 min)...</p>
<p><strong>Risks:</strong> Minimal; possible eye strain or fatigue...</p>
<p><strong>Benefits:</strong> Contribute to aging research; receive summary of results...</p>
<p><strong>Confidentiality:</strong> Data stored securely, coded with ID numbers...</p>
<p><strong>Voluntary:</strong> You may withdraw at any time without penalty...</p>

<p><em>Note: By clicking "I Understand and Agree," you indicate you have read and understood this information.</em></p>

Configuration:

{
  "content": "<h2>Study Information...</h2>...",
  "button_text": "I Understand and Agree",
  "require_scroll_to_bottom": true,
  "button_delay_ms": 5000
}

Design Recommendations

Content Design

• Clarity: Use simple, direct language
• Structure: Break content into sections with headings
• Length: Keep pages concise; use multi-page for lengthy content
• Visual Hierarchy: Use headings, bold, lists for scannability
• Accessibility: Ensure sufficient contrast, readable font size

Button Configuration

• Descriptive Text: Use context-appropriate labels ("Begin", "Next", "I Understand", "Continue to Task")
• Delay: Consider 2-5 second delay for important content to encourage reading
• Scroll Requirement: Use for critical information (consent, safety warnings)

Multi-Page Instructions

• Logical Flow: Order pages from overview to details
• Page Count: 3-5 pages maximum to avoid fatigue
• Progress Indicator: Show page numbers for orientation
• Consistency: Keep formatting consistent across pages

Common Issues and Solutions

Issue	Solution
Participants skip without reading	Add Button Delay (ms) (3-5 seconds) and Require Scroll To Bottom
Content too long for screen	Break into multiple pages; ensure responsive design
Images don't load	Use absolute URLs; check image hosting and CORS settings
HTML formatting broken	Validate HTML; escape special characters; test rendering
Participants confused about next step	Clear button text; use arrows or "Continue to [Next Task]"

Compliance Considerations

Informed Consent:

• Instructions task can DISPLAY consent information
• However, formal consent should use the study's dedicated consent form system
• Don't rely solely on Instructions task for legal consent documentation

Data Collection:

• Time-on-page data shows engagement but doesn't prove comprehension
• For critical understanding, use questionnaire task with comprehension checks

Documentation:

• Logged events provide audit trail of what was shown and when
• Content versioning important for longitudinal studies

References

This is a utility task without a specific scientific literature. General guidelines for instruction design:

• Sweller, J. (1988). Cognitive load during problem solving: Effects on learning. Cognitive Science, 12(2), 257-285. (Cognitive load considerations for instruction design)

• Nielsen, J. (1997). How users read on the web. Nielsen Norman Group. (Web content readability and scanning patterns)

See Also

• Questionnaire - For collecting participant responses and comprehension checks