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 (via the Quill editor), images, videos, and external links, making it suitable for sophisticated content presentation needs. It can also optionally collect file uploads from participants.

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. File Collection: Optionally gather file uploads (documents, images, media) from participants

Configuration Parameters

Content Parameters

Parameter	Type	Default	Description
main_instructions	string (HTML)	''	Rich-text content to display (edited as instructions_text in the form; serialized as main_instructions).
hint_instructions	string (HTML)	''	Optional hint text.

File Upload Parameters

File upload is off by default. When file_upload_enabled is true, the runtime shows a drag-and-drop upload zone and the remaining parameters apply.

Parameter	Type	Default	Range	Description
file_upload_enabled	boolean	false	—	Show the file upload zone.
file_upload_required	boolean	false	—	Block task completion until at least one file is uploaded.
file_upload_instructions	string (HTML)	''	—	Rich-text instructions shown above the upload zone.
max_files	number	5	1–50	Maximum number of files.
max_file_size_mb	number	250	1–250	Maximum size per file (MB).
max_total_size_mb	number	1000	1–1000	Maximum combined size of all files (MB).
allowed_file_types	string[]	[] (any)	—	Allowed MIME types. Config offers presets: Images (image/*), PDF (application/pdf), Documents (application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document), Videos (video/*), Audio (audio/*).

Data Output

Markers and Responses

Markers (stimulus_shown): emitted once when the page is shown. Reading time is measured from this point. No additional data fields are attached.

{
  "type": "stimulus_shown",
  "ts": "2024-01-01T00:00:00.000Z",
  "hr": 1234.56
}

Response Data (completion, recorded for every participant):

{
  "event": "instructions_complete",
  "responded": true,
  "reading_time_ms": 13450,
  "files_uploaded": 0,
  "total_size_mb": 0,
  "files": []
}

When files have been uploaded, files[] contains one entry per uploaded file with id, name, size (bytes), and type.

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": "instructions_upload_0_abc123_document.pdf"
}

File removed:

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

File upload error (additional context fields vary by error code):

{
  "event": "file_upload_error",
  "error": "file_too_large",
  "file_name": "document.pdf",
  "file_size_mb": 312.5,
  "max_size_mb": 250
}

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

Summary Artifact

The instructions task does not generate a summary artifact. When file upload is enabled, each uploaded file is emitted as a binary artifact (filename instructions_upload_{taskIndex}_{fileId}_{originalName}), handled by the participate page.

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:

{
  "main_instructions": "<h2>Welcome...</h2>..."
}

File Upload Instructions

Collect a document or other file from the participant before they continue.

{
  "main_instructions": "<h3>Upload your consent form</h3><p>Please attach the signed PDF before continuing.</p>",
  "file_upload_enabled": true,
  "file_upload_required": true,
  "file_upload_instructions": "<p>Drag and drop the file, or click to browse.</p>",
  "max_files": 1,
  "allowed_file_types": ["application/pdf"]
}

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:

{
  "main_instructions": "<h2>Study Complete...</h2>..."
}

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:

{
  "main_instructions": "<h2>Study Information...</h2>..."
}

Design Recommendations

Content Design

• Clarity: Use simple, direct language
• Structure: Break content into sections with headings
• Length: Keep content concise; split lengthy material across consecutive tasks
• Visual Hierarchy: Use headings, bold, lists for scannability
• Accessibility: Ensure sufficient contrast, readable font size

File Upload

• Required Gate: Enable "file upload required" to block completion until a file is attached.
• Type Restrictions: Restrict allowed_file_types to the formats you actually need.
• Size Limits: Set max_file_size_mb and max_total_size_mb conservatively to avoid large uploads.

Sequencing

• Logical Flow: For lengthy content, split it across several consecutive Instructions tasks ordered from overview to detail.
• Consistency: Keep formatting consistent across the sequence.

Common Issues and Solutions

Issue	Solution
Content too long for screen	Split across multiple consecutive Instructions tasks; ensure responsive design
Images don't load	Use absolute URLs; check image hosting and CORS settings
HTML formatting broken	Use the Quill editor; validate HTML; test rendering
Uploaded files rejected	Check allowed_file_types, max_file_size_mb, and max_total_size_mb against the file

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