How to document use case scenarios for legacy systems
Legacy systems rarely fail because their screens are old. They fail when nobody can explain who may perform an action, which rules apply, or where each data value came from. Clear scenario records preserve that knowledge before changes make it harder to recover.
Start with the work as it happens, including workarounds, rather than the process in an old manual. A use case scenario for a legacy system should explain the trigger, actor, sequence, outcome and important exceptions. It is an operational record, not a glossy redesign proposal.
Because old platforms often combine mainframe screens, terminal sessions, spreadsheets, batch jobs and newer APIs, small transitions can carry significant risk. Documentation should reveal those seams and show how people, data and controls move between them.
Australian market workflows often involve banks, insurers and logistics operators handling Australian dollars and GST. Local examples, such as a Sydney council, a Melbourne hospital service or a Brisbane warehouse operator, make the record easier to test against real users, vendors and operating procedures.
Ground each scenario in current work
Begin with a narrow service goal and a visible system boundary. State what the scenario starts with, what it produces, and which applications, teams and channels are included. Keep adjacent activity out of scope until the primary journey is clear; otherwise, a legacy dependency can make the scenario difficult to review.
Give the scenario a stable identifier and a plain-language title that names the job and actor. A Sydney council, for example, might document recording a water-billing adjustment through the customer-service terminal. Link each record to the service catalogue, procedure or requirement it supports while preserving the language used by operational staff.
Define actors, goals, and triggers
Separate the primary actor from supporting actors. The person requesting a change may be different from the officer approving it, a system processing a batch file, or a vendor providing support. Record internal and external roles, authorisation level and the organisation responsible for each handoff.
Each scenario should make several elements explicit:
- Actor and role: the person or system performing the work
- Goal: the outcome the actor needs to achieve
- Trigger and preconditions: the initiating event and required starting state
- Outcome: the final state and resulting record
Use these fields consistently across the project. Teams can adapt the project templates in UCDmanager’s free collaborative workspace, or inspect the demonstration project before creating a project for their own research, requirements and test evidence.
Map the sequence across old and new systems
Describe the successful path as an ordered sequence of observable steps. For each step, identify the screen or interface, input, system response, responsible role and resulting record. Include where the process waits for a batch cycle, approval or downstream service, because elapsed time often determines whether staff bypass the official route.
Follow exceptions from the point of deviation. A Melbourne hospital service might need to show how an urgent pathology result moves from an ageing interface to a laboratory system when the standard integration is unavailable. Name the fallback, who activates it, what data is delayed and how reconciliation occurs.
Record rules, exceptions, and dependencies
Write business rules so they can be tested, not merely summarised. Capture the condition, action, source and exception for each decision, including thresholds, validation messages, retention controls and manual overrides. Screenshots and database extracts can support a rule, but the documented rule must remain understandable without them.
Record dependencies with enough precision to support impact analysis. Name the upstream feed, downstream report, vendor service, shared datastore and scheduled job, then note failure behaviour and recovery steps. Where the Privacy Act 1988 and Australian Privacy Principles apply, identify collection, access, correction and consent requirements without reproducing personal information in the scenario.
Connect evidence to decisions
Attach evidence showing whether the documented flow reflects reality. Useful sources include screen recordings, support tickets, transaction samples, batch logs, field notes and interviews. Record the observation date and environment, since a legacy screen can vary by site, role, release or device.
Keep the evidence trail concise and actionable:
- Source: the artefact or research record supporting the observation
- Observed behaviour: what the actor or system actually did
- Issue or constraint: the defect, delay or limitation encountered
- Decision: the agreed action, owner and validation status
Give every defect, workaround or unresolved rule a clear status and owner. Separate confirmed behaviour from an assumption that still needs validation. A related guide to stakeholder test results explains how usability and accessibility findings can become traceable decisions linked to relevant scenarios and business rules.
Review, validate, and maintain
Review drafts with the people who perform and support the work, including frontline staff, service owners, engineers, operations, security, privacy and accessibility specialists. A Brisbane warehouse team can use a walkthrough to confirm device constraints, shift handovers and offline steps that system diagrams often omit. Capture disagreements as open decisions rather than smoothing them over.
Maintain scenarios as controlled records. Update them when a workflow, rule, interface, vendor dependency or control changes, and link each revision to its supporting evidence. For Australian Government services, the Digital Service Standard and WCAG expectations add compliance context, especially where a legacy channel remains part of a wider service. Store the result in the shared project so distributed teams can work from one traceable history. Each maintained scenario then remains a searchable account of how the service currently works and why.