A Model for Documenting Requirements Elicitation

Background

Constructing an information system is a difficult task whose issues are derived from the translation of requirements in a software project. In RE, i.e., the first stage of software engineering, needs must be identified, defined, and documented to properly meet the objectives of the system. Nevertheless, although different techniques to elicit requirements have been proposed ⁴ (whose application allows understanding such needs), most of them do not describe a model to document them and ensure that the elicitation is visible and understood by the interested parties. To achieve this goal, requirements must be properly documented in order to ensure that the parties establish common agreements about what needs to be modeled and presented as a solution to a specific problem ⁵. During this review, it was not possible to identify standard guidelines or directly related procedures on how to document the elicitation of requirements. However, different processes, specifications, standards, and initiatives use this stage as the starting point for software projects, among which the following can be mentioned:

1. Project Management Body of Knowledge (PMBOK) ⁶ is a set of management practices that constitute the basis for a project management methodology. PMBOK defines requirements elicitation as the process during which the needs of the interested parties are defined and documented through initiation, planning, execution, monitoring, control, and closing. However, although it has been widely adopted by software engineers, it does not describe what and how to document in each step.

2. Capability Maturity Model Integration (CMMI) ⁷ is a series of practices and high-level processes that help organizations build a model for improving their processes and, to a certain extent, their quality. The development of requirements is part of the third level of CMMI, and its purpose is to identify, determine, and analyze the needs of the client, but, although this level describes the procedure to be followed through 13 activities, none of them are oriented towards documenting the elicited requirements.

3. Software Engineering Body of Knowledge (SWEBOK) ⁸ is defined as a guide to knowledge for SE. Specifically regarding requirements, it defines the analysis processes of client needs in order to discover and solve conflicts, find flaws, and determine how to interact with the context. Nevertheless, this stage has a serious issue with regard to the development of a software product; it does not explicitly reference or describe a procedure for documenting elicitation.

4. There are other specifications and standards related to RE, such as ISO/IEC 12207 Information Technology - Software Life-Cycle Processes for Software Requirements Specifications, MIL-STD 490A Specification Practices, MIL-STD 498 Software Development and Documentation, SAPSS - 05 European Space Agency, ISO/IEC 9126 Information Technology - Software Product Evaluation - Quality Characteristics and Guidelines for Their Use, CMU/SEI-92-TR-012, and CMU/SEI-2006-TR-013, among others. Nevertheless, although all of them accept that the documentation of requirements is essential to quicken the processes of the lifecycle, none of them describes or proposes a model, method, or process to that effect.

Related works

In addition to the previously described background, several authors have proposed and disseminated models for eliciting requirements. During this systematic review of the literature, 73 works and relevant studies were found, out of which 10 were excluded because of their title and 45 because of their abstract. The result was a sample of 18 works that met the criteria of the search protocol. During the search, little information about the topic was found, so it was decided to include research with contents on how to document elicitation.

⁹ proposes a model that is useful when a set of complex conditions appears in a software component. However, it does not consider that, generally, the interested parties express these conditions in natural language, so these tables do not allow evaluating the resulting ambiguities before recognizing the actions as requirements. This proposal is more oriented towards creating a list of needs that are candidates to requirements. It has not been widely adopted by the community, which is evident because of the model’s little referencing and application. The proposal made by ¹⁰ acts as a bridge for the parties, which is mainly applied to model functional requirements and does not consider non-functional requirements. Additionally, it lacks well-defined semantics, which could result in different interpretations. Despite the fact that this kind of representation is used as a model of the agreement for the parties and to describe needs, as a descriptive document, it does not provide enough information for the other stages of the lifecycle. Therefore, this proposal is limited to specifications.

¹¹ structured a model for representing requirements through mathematical variables, which allow defining said requirements without ambiguities. Although this model clarifies the association of client needs with elements and mathematical variables, the problem is that the required level of mathematical knowledge is very high, and most engineers and interested parties are not able to apply it. Therefore, it has not been widely adopted by the community. According to ¹², it is necessary to collect and organize requirements based on different approaches, as do the interested parties. However, because this point of view recognizes multiple perspectives, it does not provide a framework to discover conflicts in the proposed requirements, nor does it allow managing inconsistencies. Moreover, a high number of perspectives makes it difficult to define the priority of the requirements, so the generated documentation is not enough to accept them.

The proposal made by ¹³ describes a process to elicit requirements in which the user has little participation and the formats to document them do not have a defined structure. Requirements must be expressed non-graphically and observe a specific methodology, which is not aligned with paradigms such as UML or POO. Thus, this model does not offer an efficient alternative to document elicitation, nor does it consider non-functional requirements, which must therefore be collected and documented separately. In ¹⁴, the documentation of requirements comprises a general vision and a functional description, but the product that it generates is a long document that does not offer a clear description of the needs of the parties. It adopts the IEEE STD-830-1998 standard, which is oriented towards specification, not towards elicitation.

¹⁵ propose a set of structures to better organize requirements documentation. However, they assume that natural language has no specific formal or graphic notation, so they orient their structures towards both algorithms and programming languages, which limits freedom in the subsequent codification process. Besides, these tools cannot represent the descriptions of needs made in natural language. Hence, the interested parties do not easily reach agreements. ¹⁶ describe a theoretical framework with a variety of styles for documenting the elicited requirements with regard to the variety of situations in which the software is developed. Although this can be useful and its goal is to explain the different ways in which requirements are documented in practice, until now, and according to the results of the analysis conducted in this proposal, this diversity has not been evaluated by another work, theoretical framework, or study case, which does not allow understanding its efficiency and effectiveness in the industrial practice.

In their proposal, ¹⁷ argue that, when elicitation does not present a semantically transparent model of the problem domain, the analyst must use underlying objects to document the process, but, although this procedure can yield good requirements, its development is usually slow, as one must work simultaneously with characteristics such as multilanguage, sequentiality, hierarchies, multidimensionality, and integrity for all the requirements. This increases the difficulty of documenting elicitation because many of these requirements are still unknown at this stage. Furthermore, the generated document is nothing more than a personal vision of each engineer, and it does not facilitate a proper discussion with the interested parties. ¹⁷ use tables to represent requirements, including their properties and relations. The problem emerges when the client makes modifications, as the structure of these tables is not flexible and does not allow re-processing. This lack of dynamism does not provide the engineer with maneuverability to maintain the document of elicitation up to date. Thus, the proposal does not have proper tracing.

¹⁸ use agile methods to elicit most of the essential requirements through incremental development. The point here is that agile processes for requirements do not consider the planning or design of possible future requirements, and the documentation remains insufficient at every stage. Meanwhile, ¹⁹ proposes a two-variable model, which is common in Mechanical and Electrical Engineering and is used to document requirements. Although, in theory, it is useful in software systems, it is not practical due to its volatility. Besides, it cannot easily adapt to contexts where the volatility of the client needs is high and a higher dynamism is required to keep the elicitation document up to date.

²⁰ provide templates for use cases that are informally described along the lines of software products, and they document their use. Each study case provides one or more scenarios that describe how the system must interact, but this interaction is not reflected on the tables. Therefore, any modification of the requirements creates a new data table. ²¹ developed Athenea, a tool that allows users to translate their experiences and points of view, to later negotiate the requirements collaboratively. This is an experimental tool that, after six years, has not been tested in real software development environments. Thus, it is not possible to verify its efficiency and effectiveness in creating elicitation documents.

²² describe elicitation as an important step for creating the specifications document and propose a series of templates to document it. The results include process representations, field observation notes, and interview transcriptions. However, by analyzing them, it is found that they suggest different ways for the users of the process to describe their needs, which makes it difficult to obtain the expected documentation. In this regard, the objective of the model elaborated by ²³ is to simplify, structure the elicitation process, and generate a document that presents a set of selection criteria. Although it is relevant, few works on this subject were found which describe its application in small-scale projects, so its success on a larger scale cannot be ensured.

²⁴ propose a method to elicit and document requirements based on collaboration technologies and audio records. To structure their documentation, they propose a template that uses key terms collected and defined in a glossary. Although these terms are useful to establish a common language and avoid ambiguities, the subsequent relationship with the terms used in the documentation is not clear, and traceability becomes difficult. The model presented by ²⁵ constitutes a way to analyze elicited and obtained data based on the information and the documentation regarding system requirements. However, although it is successful in terms of documentation, it does not assign a well-defined role to the interested parties. Thus, the final version is a vision by engineers and for engineers only, and it does not consider the required dialogue with clients and users.

Better practices

• Templates. They are used as a means to collect information and document processes. In elicitation, they constitute a useful tool to store the necessary data to identify and recognize the client’s needs. Some authors use them as elicitation and negotiation models, and they apply them as a complement to elicitation techniques, where the final documentation is managed directly through the interactions of the participants.

• Schemes. In practice, many works propose making different types of diagrams and schemes to observe elicitation factors in an organized way. Other works use conceptual schemes oriented towards objects that are obtained from the specification model. CASE tools are another option. These are especially used to detail the requirements and produce schemes. In general, the literature uses them to represent subsystems or components of a system, or the relations between them.

• Variable matrices. They are used as an analytic way to manage the interaction between factors in the initial layer of the logic of a program. For some authors, the variables that interact and the behavior of the system are correct only when properly documented. In general, they are used as a complement to templates because they also use variables or fields to properly associate and divide information.

• Indicators. The use of indicators allows evaluating the way in which elicitation contributes to improving problem interpretation. This vision is oriented to processes aimed at systematically defining the activities that make up a process, identifying the interrelation between them and the persons in charge, and introducing indicators to measure the results regarding the capacity and efficiency of the process. Consequently, criteria must be introduced which allow improving the elicitation process.

• Scenarios. Some authors use scenarios to describe the behavior of the system, in order to ensure a better comprehension and collaboration among parties during the requirements elicitation process, as well as to maintain the information they can recognize. This practice allows for the validation of requirements with the users. The main objective, according to the literature, is to capture the vocabulary of an application and its semantics, with the aim to facilitate the understanding of the application’s functionality, as each scenario describes a specific situation and behavior.

• Diagrams. Some works translate requirements into diagrams to show the interaction between the different actors and the system, which adds value for the user in the form of use case diagrams specifying the system behavior. That is to say, they describe what the system does, not how to do it. This practice indicates the sequence of the processes involved, the units, and the persons in charge of execution. In this sense, diagrams are the symbolic or pictorial representations of administrative processes.

Principles

• Logic and abstraction. These concepts are useful because they allow understanding, analyzing, and modeling both the problem and its possible solution while making it easier for users and clients to understand what they are interpreting, e.g., the requirements. In this research, logic is conceived as a set of principles that allows people to judge based on evidence and make decisions supported by an activity. Abstraction is the process of removing or extracting the characteristics of something in order to reduce it to a set of essential particularities. In the elicitation of requirements, these notions can be used to establish the common characteristics of the needs, objects, and procedures of the users; or when two functions perform almost the same task and can be combined. To structure the proposed semi-formal model, this research considers understanding, interpretation, modeling, problem-solving, and logical reasoning. Both are necessary principles to understand both the context and the problem to be solved; they are tools that make it easier to find the necessary information to document the elicitation process.

• Formal methods. This concept refers to techniques and tools based on principles and mathematical postulates that are used to specify, design, validate, and verify software and hardware systems, among others. The specifications used in formal methods consist of well-established statements with regard to mathematical logic. Formal verification is based on rigorous deductions; it is the logic itself, i.e., each step follows a rule of inference and can be therefore verified through a sequential process ²⁶. During the stage of requirements engineering, formal specification is important; it is a task that requires care because its function is to ensure that both the operation and the performance of the program are correct in any situation. The principles of formal methods considered while structuring the proposed model are propositional calculus ²⁷, decision tables ²⁸, set theory ⁴⁰, declarative languages ²⁹, and design by contract ³⁰

Structuring the model

Step 1. Preparing the process diagram: A process diagram is used to show the relations between the main components of a system. This diagram is also used to tabulate values of process design for the components in different operating modes. It shows the relations between the sub-processes of a system, but it hides the less important details, such as the responsibilities and denominations of agents. As a graphic representation, the model is used to visualize the process flow, showing the different activities of the system and the connections between them. This allows the interested parties to have a better comprehension of the problem, as well as to analyze the abstraction and the modeling of the solution

Step 2. Applying propositional calculus: Propositional calculus is one of the methods used to formalize natural language, whereby users can express their needs, and to structure them in the form of logical propositions ³⁵. In logic, these propositions are shown as objects of a formal language through different types of symbols, which are concatenated according to recursive rules, with the aim to build chains to which real values are assigned. By representing the needs in this way, it is possible to verify whether the interactions between the actors and the system observe the rules of the business and that, in the subsequent test activities, the expected input and output values are obtained. During requirements elicitation, it is important to represent needs as mathematical formulae, in order to structure the testing plan more easily.

Step 3. Preparing the path diagram: A path diagram is the representation of the ideal system behavior model which employs a directed graph. To this effect, a sequential node value and a priority and a dependence of execution are assigned according to the process diagram, whose edges describe the preand post-conditions. This graph shows the initial information and facilitates the construction, reading, and interpretation of the elicitation document. The iterated and represented propositions in the path diagram represent the actions that the actors perform on the system.

Step 4. Completing the elicitation template: The iterated and represented propositions in the path diagram are actions performed by an actor on the system, i.e., a process that takes place through a series of interactions, equally formed by a set of actions. Moreover, this relation generates a set of actions that the system executes as a response to actor requests. This communication produces a change of state in the variables, the values, the database, and the hardware, which must also be described. To document this actor-system-actor communication, the model proposes a template to collect the process information. The template contains the necessary information to generate a system behavior model: actor action, to detail the action performed by the actor as part of an interaction; business rules, to verify the operations, i.e., whether the resulting values are as expected and whether the test cases do not break the established rules; system action/response, to describe the actions or responses that the system executes as inner actions or as a response to a previous action of the actor; state change, to verify that the changes in the DB and those of the operational variables are the expected ones.

Step 5. Generating the requirements report: A requirements report details the first approach to the description of requirements extracted from the propositions, their type (functional or non-functional), and their relations. It is a table that serves as a complement for the template and that, put together, constitutes the benefit of the model for the next stage (requirements engineering) and the subsequent specification document. It is worth noting that, because of the constant changes in client needs, and because of the volatility of requirements, all these documentation processes can be updated dynamically, given that, without considering the action to be bottom-up or up-bottom, these results will be easily reflected on the other steps.

Application

The ATM network is one of the three pillars of any country’s banking infrastructure. It has been increasingly common to use ATMs to make it easier for the users of the financial system to make transactions, and it is useful to promote financial inclusion. An ATM has a screen, a keyboard as the main interface, and a card reader. Additionally, it can print the receipts of the transactions. Before performing operations on an ATM, the client has to log into the system. To this effect, the client slides their card to validate their information. If the card is not valid, it is returned to the client, and, if the password is incorrectly entered three consecutive times, the ATM cancels the transaction and denies access to the system. Among others, the operations supported by ATMs are deposits, withdrawals, balance inquiries, and password changes. Each of them is registered for subsequent verification and validation. In this research, and to apply the proposed semi-formal model to document the elicitation of requirements (REDOC), the withdrawal module is taken as a study case.

Step 1. Preparing the process diagram: Fig. 1 presents the sequence of activities involved in a withdrawal from an ATM. This diagram represents the relations between the parts of the ATM system, but it must be acknowledged that this system is part of a larger, more complex system that involves the bank and its relations with other systems. A visual representation provides the interested parties with a better understanding of the abstract description of a problem, and it allows them to interpret the requirements to be met for its solution.

Figure 1: Process diagram for the ATM withdrawal module

Step 2. Applying propositional calculus: After using some of the elicitation techniques, observing the users in the context of the problem, and listening to their descriptions in natural language, the process diagram is elaborated, from which the propositions shown in Table I are extracted. Since the work carried out with the interested parties is iterative, these propositions are under permanent evaluation until they are enough to solve the problem, ensuring that they describe the actions necessary to meet the needs of the parties. Table II details the propositions resulting from the iterations.

Table I: Needs as propositions

Table II: Iterated propositions

Step 3. Preparing the path diagram: The first visual approach to problem modeling, the process diagram, allows understanding the context of the problem, while a path diagram models the possible solution. For this study case, and according to the iterated propositions, the resulting path diagram is shown in Fig. 2.

Figure 2: Resulting path diagram

Step 4. Completing the elicitation template: To document actor-system-actor communication, a template has been proposed to capture the documentation of the requirements elicitation process, as shown in Table III.

Table III: Template for documenting interactions

• Actor action. This column details the action performed by the actor as part of their interaction with the system. To document it, the principle of propositional calculus in discrete mathematics is employed to translate the actions into propositions, which allows representing the requirements without ambiguities.

• Business rules. To document this column, the principles of logic and abstraction, design by contract, and formal methods are used. This, in order to transform the propositions into mathematical formulae, thus making it possible to verify the operations and whether the resulting values are the expected ones for the test cases. The changes in the main process and the alternatives, which are described in the path diagram, occur according to the documented conditions, and the appropriate path for each circumstance is taken. Moreover, the rules of the business established by the customer and the users must be observed.

• System action/response. This column uses the concept of scenarios, taken as good practice based on the literature review. It describes the actions-responses executed by the system as inner processes or in response to a previous action by the actor. Scenarios allow understanding the application and its functionality, and they describe each specific situation in this regard, focusing on its behavior and ensuring understanding and collaboration between the involved parties.

• State changes. It is necessary to know the state changes because, in the model, the tests and quality management are run parallel to the whole lifecycle of the product. This column documents the changes that occur in the database and the operating variables, with the aim to verify that they behave as expected for the system. All the information is expressed through mathematical formulae in order to structure the necessary test plan and observe the business rules. Based on the actor action and the system action/response, it is possible to know the possible state changes regarding the information entered in the system, which will be later validated when the process follows the route established in the path diagram.

Step 5. Generating the requirements report: It is worth clarifying that this report does not replace the specifications document to any extent; it only represents the result of the process of documenting the elicitation. Table IV presents the format of this report. The semi-formal language used to express the requirements in this report allows designers to understand the context in which they must work, as it suppresses many of the ambiguities of natural language, which is often used by clients when expressing their needs.

Table IV: Requirements report

Validation

To carry out this activity, five models were taken from the sample of the systematic literature review, in order to compare and analyze the results obtained in this same study case. This, according to a set of selected variables from other works that performed similar comparisons ³⁶, ³⁷, which were adapted to the objective of this research. Table Vshows the variables that were used to validate the application results of the different models vs. those of our semi-formal proposal. The process consisted of verifying the efficiency and effectiveness of each model in comparison with the results obtained with the semi-formal model.

Table V: Validation variables

From the literature, five proposals were selected, which were considered to be the most complete because of their steps and products:

• D1: Decision tables in software engineering ⁹.

• D2: Object-oriented software engineering: A use case driven approach ¹⁰

• D3: Viewpoints for requirements elicitation: A practical approach ¹².

• D4: Writing a software requirements document ¹⁴.

• D5: A template for requirement elicitation document of software product lines ²⁰.