Fixed Artifacts

In Effective Analysis, artifacts are predefined element types that serve to describe organizations, problem domains, and solutions.

The artifacts which describe concrete solutions are divided into analytical and design. Analytical artifacts represent requirements, use cases or business rules for example, whereas design artifacts describe concrete solution components such as system components (system, module, UI element), behavioral artifacts (functions, interfaces or services), data elements (data files, tables) or outputs produced by the system (documents, reports).

The following example shows how various artifacts describe different aspects of the solution and how they together form the whole picture of the system:

The main idea behind documenting using a predefined set of artifacts is unification. When there is a unified collection of artifacts created by all team members, it is guaranteed they use the common terminology and produce common outputs. Artifacts could then be assigned the same set of attributes, could be visualized in a similar way, and the relationships among them could be tracked. This all contributes to readability and overall analysis effectiveness increase.

For more details on the motivation and benefits of artifacts, refer to this chapter.

Applying this principle in practice means taking all elicitation results such as textual requirements, sketches, algorithm prototypes, and others, converting them to artifacts and storing them in a shared repository.

This principle advises using predefined artifacts. What it does not say, though, is what artifacts should be used for the given project and how detailed the artifacts’ description should be. This depends on the project, development team, and on the software development process used. Teams working on big enterprise systems, within a formal environment, with complex relationships between development teams, will probably be creating an artifact for every use case, screen or service, to keep the development manageable. On the other hand, small or agile teams will not be creating artifacts for every single part of the solution and will be ok just with sketches and notes, which are just good enough for developers to understand what they are supposed to build.

However, the previous lines apply only to documentation created for the purpose of the development of the solution. The situation is different when the documentation is created to describe the solution after it was developed. Here, no matter what process was used, the post-release documentation should be created using the fixed artifacts so that it is unified across systems and projects and easy to read.

Artifacts Instances

Throughout this text, sometimes the term artifact is used, sometimes it is replaced with artifact instance or just instance. An instance is to an artifact as a car model is to a car. Ford Mondeo is an instance of a car. Similarly, SCR Client Detail is an instance of the Screen artifact. Very often, these terms are interchangeable. If not, it should always be clear from the context whether we mean the general concept of artifacts or the concrete instance.