[Context and Motivation] Software consultancies often analyze undocumented legacy systems that have evolved over many years. [Question/problem] The lack of documented requirements, processes, and design decisions make reverse engineering these systems for analysis or reimagination a complex task. [Principal ideas/result] We detail how we utilized various requirements engineering techniques, including the development of domain stories from system screencasts, user story mapping, and process descriptions enhanced through interviews and contextual inquiries. We followed an iterative approach, with regular stakeholder feedback to fine-tune our outputs. [Contribution] We demonstrate the efectiveness of integrating these methods in legacy system analysis, sharing insights and key takeaways derived from our approach.
Legacy systems encapsulate critical business processes, making their replacement a complex
task [
In this report, we detail our methodology for analysing a legacy system. Combining varied
data collection and analysis techniques, the methodology caters to diverse stakeholder needs. For
data collection we employed document analysis, screencasts, interviews, and field observations
(see Section 4). To analyze this data we utilized domain storytelling [
Our client contracted us to document a decade-old legacy system crucial for constructing and validating machinery. The system is actively used by several hundred employees across various departments and involves significant investments. It is built on top of a database management system and uses the built-in user interface features to provide a series of forms for data entry and review. Despite functioning adequately, the system’s sparse documentation and lack of IT department oversight posed risks, particularly because it supports critical business processes and serves as an information hub.
The client requested that we produce a number of documents to serve as the foundation for a decision about the system’s future: • Software architecture and design documentation detailing the structure of the system, its components, interfaces to other systems, and implementation choices. • Requirements specifications that capture the most important high-level requirements the system currently fulfills. • Process descriptions that detail the important business processes the system supports. • Future needs that describe which features and changes need to be implemented to address upcoming requirements and technical needs.
For this consultancy commission, our team consisted of two analysts and a project owner,
with the latter primarily focusing on project management tasks. To initiate the analysis, the
client supplied us with roughly 100 documents comprising system presentations, data sharing
agreements, a developer-answered IT questionnaire, prior process analysis attempts, and a
screencast of a system demo given by one of its developers. Our client also gave us access to
the developers and some users of the system. However, due to security concerns, our client did
not share the source code, limiting our ability to create detailed technical documentation and
utilize automated analysis methods [
We followed an iterative-incremental approach from the outset: During an initial kick-of meeting with the system developers, their manager, and IT representatives, we outlined our understanding of the tasks and our proposed workflow. Their feedback and the discussions allowed us to refine our approach, particularly regarding the documents we needed to produce. An overview of our approach is illustrated in Figure 1.
The client emphasized the need for regular updates. An online Kanban board was set up to track the progress, with epics for architecture, design, requirements, process, and future needs, and stories for each of the requested documents. Wiki pages were created for each deliverable and regularly updated to keep the customer informed of our ongoing analysis. We scheduled
Set-up
working artefacts basis for
regular semi-structured interviews with the two developers, using their feedback for refinement. We also conducted an on-site visit for contextual inquiry where we were able to validate the most important business processes and observe how end-users of the system interacted with it. Backlog grooming meetings with IT representatives helped refine the scope, document the decisions and further clarified the scope of the final delivery. The project concluded with a final presentation of our results, where we received our sign-of.
4.1. Document Analysis 1–8 We initiated our document analysis by evaluating around 100 documents supplied by the client and categorizing them by utility. We found that around 38% were email archives discussing project management. Around 20% were Microsoft Word documents, about half of which were useful, because they contained data sharing agreements or meeting summaries, while the rest was mostly concerned with project management. Microsoft PowerPoint presentations made up 18% of the documents, which included both project management content (e.g., stafing) and some relevant information, e.g., about the overall IT architecture. 12% were PDF files, largely duplicative or unrelated. Excel spreadsheets accounted for 7% and contained partial results of a previous analysis attempt and were disregarded on request of the customer.
The number of useful documents came to 25 which two analysts could analyse in a reasonably
short time. Their content was mostly unstructured so that typical automated approaches, e.g.,
using natural language processing (see, e.g., [
The demonstration made it possible for us to start systematizing the information with a focus
on the involved roles, the role-specific views, and processes the system supports. We captured
this information in domain story diagrams (see Section 5.1), highlighting role-specific system
access which informed our initial business process drafts. We started sketching a domain model
to capture the vocabulary and the relationships between the concepts of the domain. Although
incomplete, this model was useful in the exploratory phase of our research.
4.3. Interviews
Productive semi-structured interviews with the developers became the main driver of our
interative-incremental production of artifacts. Document and video analysis allowed us to
quickly produce draft versions of the required artifacts, in particular of the domain stories.
These drafts were then validated and refined based on the interviews, usually when we had
completed another chunk of analysis we wanted to discuss. In many cases, we had specific
questions that we wanted to discuss. Live editing of these drafts during the interviews proved
to be particularly helpful: The interviewees could directly comment on the changes one analyst
made while the other analyst conducted the interview.
4.4. Contextual Inquiry
Through Contextual inquiry we were able to witness users in their normal work environments,
revealing crucial functional details about how the system is used to complete the diferent
workflows of the users [
5.1. Domain Story Telling
Domain storytelling [
During our experience, we made a number of observations which are supported by existing
literature. Among them are that management-oriented documents often lack the granular
information required for technical analysis [
Screencasts as a source for requirements: The screencast proved to be a valuable tool in
reconstructing requirements, complementing the existing knowledge on how videos enhance
requirements engineering practices [
Observation: To the best of our knowledge, the current body of work does not address using analysis of system-screencasts to reconstruct requirements and domain information.
Lesson Learned: The screencast proved valuable in all phases of our analysis, enabling us to revisit specific topics to discover details and answer questions that arose with a deeper understanding of the system over time.
Contextual inquiry as a powerful tool: Contextual inquiry provided a full view of user
workflows and software limitations, proving critical for understanding complex systems where
interviews may miss nuanced workflow elements [
Observation: We discovered that gaps in our understanding often aligned with corresponding gaps in the software’s functionality.
Lesson Learned: Contextual inquiry is essential in legacy software analysis to comprehend entire workflows and identify software functionality gaps.
Redundancies in produced artifacts: We were initially reluctant to add artifacts that
capture similar information. In particular, the client’s request to create BPMN diagrams to
depict the business processes seemed to replicate the domain stories we had already created. In
general, redundant information is frowned upon in software engineering [
Observation: Artifact redundancy was beneficial. Domain stories, BPMN diagrams, and user story maps each provided unique insights despite overlapping information, catering to diferent stakeholder needs and purposes.
Lesson Learned: Selecting purpose-specific artifacts adds value to both the analysis process and stakeholder understanding for legacy systems.
In this short paper, we discuss our preliminary results of combining diferent requirements engineering techniques, including interviews, contextual inquiry, domain storytelling, and user story mapping, in the analysis of a legacy software system. Our lessons learned include the benefits of screencasts of the system in action, understanding when in the analysis contextual inquiry is valuable, and realizing the utility of redundant artifacts in analyzing legacy systems. We believe our experiences will be useful to practitioners that are faced with a similar tasks and researchers interested in sharpening the tools at the disposal of requirements engineers in the ifeld. As future work, we are going to extend our analysis and combine our preliminary results with lessons learned from a second case in which we employed the same iterative approach.