Skip to content

Question Lifecycle

Annotation questions in SyRF now follow a two-phase lifecycle: free-form drafting followed by controlled, versioned editing. This guide explains how to create questions, assign them to stages, and manage them once a stage goes live.

Overview

When you set up annotation questions for your project, you work in two distinct phases:

  1. Drafting -- Create and edit questions freely. Change anything at any time. No restrictions, no version history, no impact on annotators.
  2. After activation -- Once you enable a stage, its questions become versioned. Every edit creates a new version (v2, v3, and so on) while preserving the complete history of what was asked and when.

This lifecycle gives you the flexibility to iterate during design and the traceability you need once real data is being collected.

flowchart LR
    A[Create Draft<br/>Questions] --> B[Assign to<br/>Stage]
    B --> C[Preview<br/>Form]
    C --> D[Activate<br/>Stage]
    D --> E[Questions<br/>Versioned]
    E --> F[Edit Creates<br/>New Version]

Who This Guide Is For

  • Project Administrators -- You create and manage annotation questions, assign them to stages, and control versioning
  • Reviewers/Annotators -- You are not directly affected by question versioning. You continue to see and answer questions as before. Behind the scenes, each of your answers now records which version of the question it was collected against

Creating Draft Questions

To create annotation questions for your project, navigate to the Question Management page and open the Design tab. This is your workspace for building questions before any stage is activated.

Adding a Question

  1. Click Add Question to create a new draft question
  2. Choose a question type:
  3. Yes/No -- A simple toggle for binary decisions (e.g., "Were animals randomised to experimental groups?")
  4. Dropdown -- A single selection from a defined list of options (e.g., "What type of surgery was used?")
  5. Checklist -- Multiple selections from a list (e.g., "Which outcome measures are reported?")
  6. Free Text -- An open text field for qualitative responses (e.g., "Describe the study limitations")
  7. Number -- A numeric input for quantitative data (e.g., "What was the sample size?")
  8. Autocomplete -- A type-ahead search against a defined option list (e.g., "Select the drug name")
  9. Enter the question text -- this is the wording annotators see
  10. Optionally add help text to provide guidance alongside the question
  11. For dropdown, checklist, and autocomplete types, add your answer options

Setting Up Conditional Questions

Questions can be nested so that a child question appears only when specific answers are given to the parent question. To create a conditional question:

  1. Select an existing question in the Design tab
  2. Click Add Related to create a child question
  3. Configure which parent answers trigger the child question to appear

For example, if you have a question "What type of model is used?" with options "Pharmacological" and "Surgical", you can add a related question "What drug was administered?" that appears only when "Pharmacological" is selected.

Child questions nest beneath their parent in the question tree. You can create multiple levels of nesting.

Organising Questions

The Design tab displays your questions as a hierarchical tree. To organise them:

  • Drag and drop questions to reorder them within the tree
  • Drag a question onto another to make it a child (creating a conditional relationship)
  • Questions are grouped by category (e.g., Study Design, Outcomes, Risk of Bias)

You can expand and collapse nested question groups for easier navigation.

Editing Drafts

While questions are in draft form, you can change anything:

  • Question text and help text
  • Answer options (add, remove, reorder)
  • Question type
  • Parent-child relationships
  • Category assignment

Draft questions are fully mutable. There is no version history at this stage, and no downstream impact from changes. Iterate as much as you need.

Assigning Questions to Stages

Once you have designed your questions, switch to the Assign tab to configure which questions appear in each stage.

How to Assign

  1. Select a target stage from the stage selector (the stage must be disabled)
  2. The interface shows two panels: Unassigned Questions (left) and Assigned Questions (right)
  3. Drag questions from unassigned to assigned, or use the Assign/Unassign buttons
  4. Reorder the assigned questions to set the display order annotators will see

Parent Integrity

If you assign a child question to a stage, all of its parent questions are automatically included. This ensures the conditional logic works correctly -- a child question cannot appear without the parent question that controls when it is shown.

Assigning to Multiple Stages

The same question can be assigned to multiple stages. This is common when different stages share some common questions (for example, study-level questions that apply to both screening and annotation stages).

Previewing Before Activation

Before you commit to activating a stage, use the Preview tab to see exactly what annotators will see:

  1. Select a stage from the stage selector
  2. The preview renders the annotation form with all assigned questions in their display order
  3. Check that conditional questions appear and hide correctly
  4. Verify that dropdown options, help text, and question ordering look right

The preview uses the current state of your draft questions. Take time to review it carefully -- once you activate the stage, changes to questions create versions rather than simple edits.

Activating a Stage

When you are satisfied with your question design and assignment, enable the stage. Activation triggers the following:

  1. Questions become versioned -- Each draft question assigned to the stage is permanently converted into a versioned Annotation Question. The draft ceases to exist.
  2. Version 1 is created -- Each question receives its first version (v1), capturing the exact text, options, and settings at that moment.
  3. Structure is locked -- The question's fundamental structure (its type, parent relationships, and grouping) is fixed from this point forward. These cannot change because doing so would invalidate existing answers.
  4. Question set snapshot -- The system creates an immutable snapshot of which questions (at which versions, in which order) are assigned to the stage. This snapshot is preserved permanently.
  5. Stage opens for annotation -- Annotators can now begin working in this stage.

Activation is a one-way operation. Once activated, the stage's questions follow the versioning model described below.

What Happens After Activation

Versioned Editing

After activation, you can still improve your questions, but each change creates a new version:

What you can change (creates a new version): - Question text (wording improvements, typo fixes) - Answer options (add a missing option, remove an incorrect one) - Help text (improved guidance)

What you cannot change after activation: - Question type (e.g., you cannot convert a dropdown to a checkbox) - Parent-child relationships (the question hierarchy is fixed) - Grouping behaviour

To change a structural property, you need to create a new question.

How Versioned Editing Works

  1. Open a question in the Design tab -- a version badge shows the current version (e.g., "v1")
  2. Make your content changes. Changes are auto-saved as you work, but they remain as a draft edit until you commit them.
  3. When you are ready, click Save as New Version. The system creates a new version (e.g., v2) with your changes.
  4. Optionally record a change reason explaining why you made the edit

The new version is available immediately. All previous versions are preserved permanently, creating a complete history of how each question has evolved.

Version Numbers and Badges

Every question card displays a version badge (e.g., "v3") showing its current version number. This gives you an at-a-glance view of how many times each question has been revised.

  • v1 indicates the question has never been changed since activation
  • v2, v3, etc. indicate the question has been refined over time

See the Question Management UI guide for details on viewing version history and comparing versions.

Annotations and Version Tracking

When an annotator answers a question, the system records which version of the question they were answering. This means:

  • Annotations collected against v1 remain linked to v1, even after v2 is created
  • You can always reconstruct exactly what an annotator saw when they recorded their answer
  • Reconciliation (comparing answers from different annotators) compares answers to the same question version

This version tracking happens automatically. Annotators do not need to do anything differently.

Understanding Question Sets

Each stage maintains a Question Set -- a versioned record of which questions (at which versions, in which order) annotators see when they work in that stage.

When you add a question, remove a question, or upgrade to a newer version of a question, the system creates a new Question Set Version. Previous versions are preserved, so you can always reconstruct exactly what the annotation form looked like at any point in the project's history.

This is particularly important for systematic reviews where traceability and reproducibility are required by journals and funders.

Tips for Getting Started

  1. Start with drafts -- Do not worry about getting everything perfect. Create your questions, review them with your team, and iterate freely during the draft phase.
  2. Use the preview -- Always check the Preview tab before activating a stage. Make sure conditional logic works and the question order makes sense.
  3. Version strategically -- After activation, small improvements (fixing a typo, adding a missing option) are safe and encouraged. Each creates a clean version record.
  4. Communicate with your team -- When you create a new question version, consider notifying your annotators so they are aware of changes.