Skip to content

Question Management UI

This guide covers the administrative tools for managing versioned questions after a stage has been activated. You can view the complete history of changes to any question, compare versions side by side, and make informed decisions about what happens to in-progress work when you update your questions.

Overview

Once a stage is activated and questions become versioned (see the Question Lifecycle guide), you need tools to manage those versions effectively. The Question Management UI provides:

  • Version badges on every question card, showing the current version at a glance
  • Version history for any question, showing every change with timestamps and change reasons
  • Side-by-side comparison between any two versions of a question
  • A versioning wizard that guides you through creating new versions
  • A decision framework for handling in-progress annotation sessions when you update questions

Version Badges

Every question card in the Design and Assign tabs displays a version badge -- a small label showing the current version number (e.g., "v3").

At a glance, version badges tell you: - v1 -- This question has not been changed since activation - v2, v3, etc. -- This question has been revised. Higher numbers mean more revisions - In the Assign tab, the badge shows which version is currently assigned to each stage

Viewing Version History

To see the complete history of changes to a question:

  1. Select a question in the Design tab
  2. Open the Version History panel
  3. The panel shows a timeline of all versions:
  4. Version number (v1, v2, v3, ...)
  5. Who created it -- the administrator who made the change
  6. When -- the date and time of the change
  7. Change reason -- the optional explanation recorded when the version was created

The version history provides the audit trail required for systematic review traceability. Every change to every question is recorded with attribution and timestamp.

Comparing Versions

To see exactly what changed between two versions:

  1. Open the Version History panel for a question
  2. Select any two versions to compare
  3. The system displays a side-by-side diff highlighting exactly what changed:
  4. Added text is highlighted in green
  5. Removed text is highlighted in red
  6. Answer options show additions, removals, and reordering
  7. Help text changes are displayed similarly

The diff view helps you understand the evolution of a question over time, and is useful when auditing the annotation protocol for a systematic review report.

Creating a New Version

When you need to update an activated question (fix a typo, add a missing option, improve help text), the versioning wizard guides you through the process.

Steps

  1. Open the question in the Design tab. The version badge shows the current version.
  2. Click Edit to enter editing mode. A banner reminds you that changes will create a new version, not overwrite the current one.
  3. Make your changes:
  4. Edit the question text
  5. Add, remove, or reorder answer options
  6. Update help text
  7. Click Save as New Version
  8. Optionally enter a change reason explaining why you made the edit (e.g., "Added 'Other' option based on reviewer feedback")
  9. Optionally mark whether the change is breaking or non-breaking:
  10. Non-breaking -- The change improves the question but does not invalidate existing answers (e.g., adding an option, fixing a typo)
  11. Breaking -- The change may invalidate some existing answers (e.g., removing an option that annotators had selected)
  12. Confirm to create the new version

The system creates the new version immediately. The previous version is preserved permanently.

Handling In-Progress Annotation Sessions

When you update a stage's question configuration (upgrade to a new question version, add new questions, or remove questions) and annotators have work in progress, you need to decide what happens to their sessions.

The Decision Process

When you save changes to a stage's question set, the system presents a series of choices:

Step 1 -- Scope: - Pin all sessions to the old configuration? If yes, only new sessions use the updated questions. Existing annotators finish with the questions they started with. - Update all sessions to the new configuration? If yes, proceed to the next steps. - Update only incomplete sessions? Complete sessions keep the old configuration; incomplete sessions are updated.

Step 2 -- For non-breaking changes: If the update does not invalidate any existing answers: - Carry forward answers -- Existing answers are preserved and linked to the new question version - Clear and re-answer -- Existing answers are cleared so annotators re-answer with the new version

Step 3 -- For breaking changes: If the update may invalidate some answers (e.g., a selected option was removed): - Update anyway -- Sessions are updated to the new version. Answers that are no longer valid are cleared and flagged for the annotator to re-answer. - Leave on old version -- These sessions keep the old configuration to avoid disrupting the annotator's work.

Impact Preview

Before you confirm, the system shows you a summary: - How many sessions will be updated - How many sessions will remain on the old configuration - For breaking changes, which specific sessions are affected and why

This helps you make an informed decision based on your project's needs.

Practical Examples

Adding a missing dropdown option (non-breaking): You add a new option to a dropdown question. This is safe -- no existing answers are invalidated. You can carry forward existing answers or clear them, depending on whether you want annotators to reconsider their choices.

Removing an option (potentially breaking): You remove an option that some annotators have already selected. The system identifies which sessions are affected. You can pin those sessions to the old version (so annotators finish with what they have) or update them (clearing the invalid answers so annotators can re-select).

Adding a new question to a stage: A new question appears in updated sessions as an unanswered item. Annotators see it the next time they open their work.

Tips for Managing Versions

  1. Use change reasons -- Recording why you made each change creates a valuable audit trail. Months later, you (or a journal reviewer) can understand the rationale behind each revision.

  2. Prefer non-breaking changes -- Adding options, improving wording, and updating help text are safe changes that do not disrupt in-progress work. These should be the majority of your edits.

  3. Pin when in doubt -- If you are unsure how a change will affect annotators mid-session, pin existing sessions to the old version. New sessions get the updated questions, and there is no disruption to work in progress.

  4. Check the diff before confirming -- Always review the side-by-side comparison to make sure your changes are correct before creating a new version.