Architectural-Toolbox-Description.md

@@ -5,7 +5,7 @@ AS deteriorate the evolvability and maintainability of the classes and packages
 
 The toolbox is comprised of three tools: Arcan for Java systems, Arcan for C/C++ systems, and ASTracker. ASTracker can instrument both versions of Arcan to enable a more simple experience for the user and avoid them the trouble to learn three tools.
 
-The sections below provide further details on architectural smells and the role of each tool provided by this toolbox.
+The sections below provide further details on architectural smells.
 
 # Architectural smells
 There are four types of architectural smells supported by the toolbox.
@@ -75,4 +75,17 @@ The characteristics considered in our work are:
    *   Average internal path length: Only computed on package HL. The average length of the paths between internal nodes with afferent dependencies and internal nodes with efferent dependencies within the central package. The shorter the length, the more the packages that depend upon the main component and packages that are depended upon by it are connected.
    *   Affected classes ratio: Only computed on package HL. The ratio between the number of classes taking part in a dependency relationship with afferent and efferent packages of the main component and the total number of classes in the main component.
 
-# Tooling
\ No newline at end of file
+The smell-generic characteristic Overlap, Centrality, and Size are of interest because they are all metrics that are conceptually related to the complexity caused by any instance of a smell in the system. Intuitively, all of them may hinder the degree of understandability, extensibility, or generally of maintainability of the components affected by a smell: the more elements a smell has (size), or the more elements of a smell are also involved in other smells (overalp), or the more its elements are interacting with other important components of the system (centrality), the harder it is to fully understand or to refactor the smell. 
+
+Age, on the other hand, allows us to track the evolution of the other characteristics over time, identify periods where they are more impactful, or discern eventual correlations between them.
+
+The CD smell-specific characteristics Shape and Average edge weight are of interest because they are directly related to the complexity of the smell.
+The more complex the shape, and the more edges there are between the affected components, the harder the smell is to refactor because more effort is required.
+The Affected design level, similarly, is important because the cycles present at both package and class level have an impact on two different levels at once.
+Finally, the Number of inheritance edges characteristic is considered because inheritance edges are considered an indicator of an intentional design choice, thus intentional cycles that contain a high number of inheritance edges between the components may be more interesting for a developer to inspect.
+
+The UD smell-specific characteristic Instability gap and Strength are of interest because they are used for the detection of the smell and thus can effectively measure its criticality. The higher the instability gap, the higher the chance the component affected by the smell is changed due to ripple effects. Likewise, the higher the strength, the higher the chance (because there are more possible components that are prone to a change) a change occurs and propagates to the affected component.
+
+The HL smell-specific characteristics Affected classes ratio and Average internal path length are of interest because they quantify the involvement of the internal classes in the smell by answering the questions `How many classes belonging to the affected package (out of all package classes) contribute to the smell?' and `How much efferent and afferent packages are actually connected?', respectively.
+Intuitively, if the average internal path length is low, it is easier for changes to propagate through the components involved in the smell. And if the efferent and afferent packages are poorly connected (i.e. few paths), the chance a change propagates is small.
+In other words, these two characteristics measure the proneness of a HL smell to propagate changes incoming from its dependencies to the components depending upon it.