Skip to content

Question Management UI

Summary

Phase 6 adds the administrative tools project administrators need to manage versioned questions effectively. This includes viewing the complete history of changes to any question, seeing at-a-glance version badges, comparing versions side by side, and making informed decisions about what happens to in-progress work when question configurations change.

The Problem

Phase 4 introduces question versioning, but without dedicated management tools, administrators would have no way to see their version history, understand what changed between versions, or manage the practical consequences of question changes. For example, if an administrator updates a dropdown question to add a missing option, what should happen to annotators who are currently mid-session with the old version? Without a structured decision process, administrators would be guessing.

What We're Building

For Project Administrators

Version history and comparison: - Every question card displays a version badge (e.g., "v3") showing its current version at a glance - Opening a question's history shows a timeline of all versions: who changed it, when, and why - Selecting any two versions shows a side-by-side comparison highlighting exactly what changed -- added options, modified text, updated help text

Versioning wizard: - When an administrator edits an activated question, a clear wizard guides them through creating a new version - The wizard explains that a new version will be created (not an overwrite) and prompts for an optional change reason - The administrator can mark whether the change is "breaking" (meaning existing answers may no longer be valid) or non-breaking (a safe improvement)

Decision framework for active sessions: When a stage's question configuration changes and annotators have work in progress, the administrator is presented with a structured set of choices:

  1. Scope -- Apply the change only to new sessions, or also update existing ones?
  2. Non-breaking changes -- Carry forward existing answers to the new version, or ask annotators to re-answer?
  3. Breaking changes -- Update sessions anyway (marking affected answers for re-review), or leave them on the old configuration?

The system shows a preview of how many sessions will be affected before the administrator confirms.

For Reviewers/Annotators

Annotators are not directly affected. If an administrator decides to update their in-progress session to a new question version, they will see the updated questions the next time they open their work. If the administrator pins their session to the old version, they continue uninterrupted.

Key Decisions

  1. Admin decides, system does not prescribe -- When question configurations change mid-project, there is no single "right answer" for how to handle existing work. The system provides the tools and information; the administrator makes the call based on their project's needs.

  2. Breaking change flag is advisory -- The administrator marks changes as breaking or non-breaking based on their intent, but the system also performs automatic detection. If a "non-breaking" change actually invalidates a specific annotator's answer (e.g., they selected an option that was removed), the system flags it regardless of the administrator's classification.

  3. Phase 6 runs in parallel with Phase 5 -- The management UI and the annotation form are independent features that share Phase 4 as a prerequisite. Building them in parallel accelerates delivery.

How It Connects

Phase 6 depends on Phase 4 (Question Lifecycle) for the versioning model it manages. It can run in parallel with Phase 5 (Annotation Form v2). Together, Phases 4-6 form the complete Question Management platform that ships in Release 1 via Phase 7 (Migration).

See also: Platform Architecture | Product Overview Related briefs: Question Lifecycle | Annotation Form v2