Artifacts and Models

Artifacts are elements that represent aspects of the solution and the environment in which the solution exists or will exist. Artifacts could describe capabilities of the solution (Requirements and Use cases), solution designs (for example, Screens, Services, and Tables) or aspects of the problem domain (Processes, Business Rules, domain Terms, etc.). Artifacts are analyzed and modeled during the analysis and design phases. There they serve as input to development, and some of them are consequently transformed into the documentation after the solution is released.

Having a set of predefined artifacts enables teams to standardize their analysis and design outputs across projects, which improves the readability of the materials and simplifies the onboarding of new team members. Since the artifact types and the way they are specified and structured is unified, it is very easy to switch between projects as the artifacts look very similar. Each artifact is basically an object, with the defined type, identifier, attributes, and relations to other objects. This dramatically improves reuse of artifacts in multiple places, thanks to the identifier it is possible to uniquely reference them and continuously built relations enable tracking of dependencies between artifacts, which is crucial to detect impacts of future changes.

Standard artifacts are beneficial during analysis where they help unify the outputs but are as crucial for documenting already released solutions so that all solution specifications look very similar and conform to the same rules. Having consistent documentation composed of the unified artifacts greatly supports the ability of the team to search for information quickly and makes switching between projects and solutions easier.

Requirement

Requirements are not just "System shall …" statements. They could be represented by a simple textual statement, as well as by complex algorithms and models. Even a user interface screen description could be a requirement if the stakeholder gave it to you and asked you to implement it as it is. So what is the relationship between a requirement and an artifact? Basically, a requirement is one of the artifacts. It is an object, holds some metadata that describes it, such as name, description, author, and priority, and could be related to other artifacts. But on the other hand, it is very common to describe the requirement itself using other artifacts. For example, when the development team is supposed to implement a system interface with the given input and output, then even though the interface is a design artifact, it is actually also a requirement.

Use Case

Use cases describe the interaction between user and system, usually specified in the form of a textual scenario. The scenario looks like a "ping-pong" played between the user and the system - user's action in the system triggers system's response:

UC Create New Game

1. User selects to create a new game
2. System displays a wizard for entering game parameters
3. User enters game information and selects the desired map
4. If the map is a multiplayer map, user selects players for the game
5. System creates the game and sends notifications to invited players
6. Use case ends

The goal of use cases is not to create a detailed specification that would enable the complete development of the system. Their purpose is to understand the scope of the system, so they provide just a high-level overview of what users want to do with the system, not how. Use cases state what capabilities users expect from the system, but they do not say any implementation details such as user interface descriptions, data structures specifications, or possible integrations.

Use cases can also be represented by a use case diagram, depicting who (actor) performs what (use case) in which system (boundary):

Activity

Use cases are an excellent tool for understanding how users intend to use the system. Additionally, a list of use cases also helps to get an initial idea of the system scope. However, use cases themselves are not sufficient for the successful system implementation, since the included amount of information does not provide enough detail. For example, most use case steps are not atomic, and to provide the necessary detail, they need to be broken down into more detailed substeps. These substeps have their own scenarios and therefore very often remind "mini use cases". Calling them use cases would not be the right approach, though, as use case analysis has a specific goal, and including these substeps into them would break it. This is why in Effective Analysis the detailed steps are not called use cases but "activities".

Activities have their own scenarios that are very similar to the scenarios of use cases, but unlike use cases, activities could be further decomposed into more detailed activities until the desired level of detail suitable for development is reached. It is really up to analysts how deep with the analysis they will go and how detailed the description of the activities at the lowest level will be. But the rule is, activity is not just a system function and involves some user interaction.

Application Component

An application component is a representation of a system or a logical system module. Components are used to describe systems and applications the company operates or develops, their capabilities, and relationships among them. The benefit of having a list of systems in the form of unique objects is the ability to model relationships between them, identify dependencies, and to discover impacts of potential changes.

Function

An application function describes the internal behavior of an application component. For example, if it is needed to explain the calculation of a grand total of an invoice, it could be done using a calculateGrandTotal() function. But function does not have to be always a calculation. Other examples could be: storing a contact to the database, executing a long-running job, or invoking an external service. Even though the name "function" could evoke a real part of the system, in this context, it is not an implementation artifact; it is not a real system procedure or a method written in some programming language. It is rather an analysis artifact that describes a logical procedure without saying how it will be implemented in the real programming language.

Service

An application service exposes the functionality of components to their environment. If the Customer Management System can create a new contact and wants to enable other systems to invoke this function remotely, it will expose this function through a createContact() service. Again, it is just a logical artifact not related to any particular technology. It says that such functionality could be invoked on this system, but it does not say anything about the underlying implementation. For example, whether it will be made available as a web service or anything else.

Interface

An application interface is the (logical) channel through which the services of a component can be accessed. For example, if the Customer Management System lets other systems manipulate its contacts remotely, it will provide the Get Client and Delete Client services, which will be logically grouped and exposed through the Contacts interface.

Domain Model

A domain model is a graphical representation of the most important entities forming the problem domain and relationships between them. It is used to understand the basic terms and how they relate to each other, so it is a great tool to provide an introduction to the realm. It is usually modeled using a UML class diagram:

Activity Diagram

An activity diagram visually presents a series of actions and the flow of control in a system or in a process. Depending on the selected level of detail, it can represent a description of very low-level system behavior on the one hand (a calculation, for example) or a high-level business process on the other.

The above example represents this flow:

1. Open new game wizard
2. Enter game parameters and select map
3. If the selected map is a multiplayer map, select players
4. Create a game
5. If the selected map is a multiplayer map, the game center notifies all invited players

Sequence Diagram

A sequence diagram is used primarily to show the interactions between objects in the sequential order that those interactions occur. Unlike activity diagrams, which also show the order of the steps, sequence diagrams are primarily focused on the interacting objects. The objects send messages to each other, which always invokes a reaction. For example, the Player sends Create Game message to the Game Center, which triggers opening a new game wizard:

The above example represents this flow:

1. Player creates a game in the game center
2. Game center opens a create game wizard and shows it to the player
3. Player enters game parameters
4. Player saves the parameters
5. Game center creates the game
6. If the selected map is a multiplayer map, the game center notifies all invited players