Software Artifacts Vs. Requirements

The relationship between artifacts and requirements is not straightforward. Not only because a requirement itself is also a type of artifact, but mainly because artifacts could represent both requirements and designs. While some artifacts represent what users really want from the system and are part of the contract with the stakeholders, others can be just internal designs "hidden" from the stakeholders.

Depending on the concrete project, selected development approach and other conditions, the following scenarios could occur:

1. The development team can design the system from the high-level requirements
   • Thanks to the agility, working communication, and strong collaboration within the team, the solution will be developed directly from the high-level requirements, without any design artifacts.
2. Analyst outlined software artifacts directly from the high-level requirements elicited with the stakeholders
   • No high-level requirements specification is created and the software artifacts are the only documentation
3. Analyst identifies high-level requirements, then creates concrete designs and represents them by software artifacts (screens, interfaces, processes, etc.)
   • "User must be able to create a new invoice. Following invoice data are required:... " -> SCR Add Invoice (Fields: ...)

Apparently, the least effective way is number 3, which requires a two-step analysis. Nevertheless, it is also the most common as it reflects the way analysis is usually done: starting with very high-level ideas and continuously elaborating them in more detail using concrete design artifacts. Until some point, the process is more or less sequential. Things get complicated, though, when the requirements start to change and the sequential process begins to circle. For example, if the list of required invoice fields changed, it means the requirement must be changed, which implies the need to change the associated screen artifact as well. This is painful as it first breaks the Avoid Duplication principle, and second, changing something twice is a waste of effort.

Ideally, there should be only a single source of truth so that no synchronization of requirements is needed. Once the requirements are expressed as software artifacts, the requirements management is done on the artifact level, so the changes are not updated back to the original textual requirements. It does not mean the textual requirements must be discarded. They should be kept to provide the context of the artifact, They provide the context for the software artifact, so it is good to keep them, perhaps in the form of a note. The primary goal is to develop the solution, not to synchronize requirements back and forth (working software is the primary goal).

Summary:

1. High-level textual functional requirements are not necessary and nobody will miss them if the concrete designs are available. Textual requirements are only needed when the analyst starts from scratch and have no idea about the solution.
2. Once the textual requirements are transformed into artifacts (screens, use cases, business rules, etc.), they are not needed anymore
   • This is not always possible, especially in environments where textual requirements specifications must be used as a communication tool
3. If design artifacts are available, related requirements should be reflected directly to the artifacts
   • Requirement "List of invoices must be sorted by the total invoice amount" specifies the concrete list on the concrete screen so it should be placed there
4. If the required change is directly related to a specific artifact, there is no need to describe it in text. So if the analyst knows that what the stakeholder really needs is changing the button color from red to green, the valid form of requirement is to state: "Change the color of the red button on SCR-123 to green".