Guideline: Using Method Content Variability

This guideline explains how to utilize method content variability to modify an existing element without directly changing the original element's base definition, or to create a new element based on an existing element. Changes are defined in a separate content package or plug-in, and the original plug-in is kept intact. Thus, it allows you to change method elements by simply changing a configuration (in other words, changing what plug-ins and packages are included in the configuration).

Variability involves textual attributes and relationships. In other words you can use variability to add, delete change, or reuse both text and relationships.

Variability is defined between two elements of the same type:

Base element: The target of the variability; the element being changed (or used as a base for new element)
Variability element: The element containing the changes (or new content or relationships) to be combined with the base

The base element is never changed directly. All changes (or new content) is defined in the variability element. The variability element specifies which element is the base.

As shown in Figure 1, when both the base element and the varaibility element are inlcluded in a configuration, the configuration "resolves" the variability to produce the result, where that result depends on what variability was used.

Figure 1. Method content variability elements

variability_elements

There are different types of variability, each with their own characteristics, rules, pros and cons. Table 1 provides a summary of the different types of variability and when you might want to use them.

**Table 1. Method Content Variability Summary**
Variability Type	Result	Possible Uses
Contributes	Contributing element adds to the base element (result = base element plus contributed characteristics) Contributing (variability) element adds to the base element. The base appears in the published Web site, but the contributing element does not. Incoming and outgoing relationships from the contributing element are added to the base Exception: If the relationship is a "to one" relationship (for example, a task has at most one primary performing role) then the relationship in the contributor is ignored if the base already has one. Text from the contributing element is appended to corresponding base sections. A base element can have more then one contributor. Contributes works transitively (a contributing element contributes its own contributors).	Add guidance to an existing element Add steps to an existing task Add responsibility for a work product to a role Add a primary performing role to a task Add a work product to a task (as an input or output work product) Add text to existing elements Adding method elements to existing categories
Replaces	Replacing element replaces parts of the base element (incoming relationships remain) (result = new element, no base element) Replacing (variability) element replaces parts of the base element. The replacing element appears in the published Web site but the base element does not. Outgoing relationships in the replacing element are maintained, and the base's are ignored. Incoming relationships to the base are maintained and added to the replacing element. Exception: If the replacing element has an incoming to-one relationship (for example, a replacing a role that includes a task performs the role relationship), the replacing element replaces that relationship in the base element. Text in the replacing element is left maintained, the base's text is ignored. A base element can only be replaced by one replacing element at a time. If two elements replace the same base element, only one can be used for interpretation (the plug-in containing one of the replacing elements needs to be removed from the configuration or no replacement will take place). Replacement works transitively (if a replacing element is replaced itself, then the final replacing element will prevail).	Replace an existing method content element with another method content element
Extends	Extending element inherits characteristics of the base element (result = base element + new element) Extending (variability) element inherits characteristics of the base element. The base element is unchanged. Both the extending element and the base appear in the published Web site. Outgoing relationships from the base are added to the extending element. Incoming relationships in the extending element are maintained, and the base's are ignored. Text is included in the extending element from the base element if the extending element did not include any text for the given section. Extends works transitively (if an extending element is extended itself the second extension inherits from its direct and indirect base elements).	Define a new element that looks just like an existing element, with some modifications (in other words, define a variant or a specialization of an existing element) Extends is not used to modify an existing element
Extends-Replaces	Replacing element replaces only values that have been redefined in the replacer (result = new element, no base element) Combines the effects of extends and replaces variability, allowing you to selectively replace specific attributes and relationships of the base element. Extending-replacing (variability) element replaces values in the base element that have been redefined in the extending-replacing element . All other values of the base element are unaffected. Both the extending-replacing element and the base appear in the published Web site.	Rename an existing element Replace a specific textual attribute of a method element Replace the outgoing relationships of an existing method element Replace the incoming relationships of an existing method element

For detailed information on how the different kinds of method content variability affect the different method element relationships, see the attached spreadsheet (Variability Cheat Sheet.xls).

Order of Evaluation

Contribution precedes replacement (the contributes relationship is resolved first, followed by the replaces relationship). The evaluation of contribution and replacement is performed top-down in the specialization hierarchy.

Handy Tricks

If you ever find that you want to create an element that looks just like an existing element, but includes some additional content, you can use a combination of extends and contributes to achieve the desired result. To do this, perform the following steps:

Define a method element that that extends the original base element. This results in a new element that looks just like the original element.
Define another method element that contributes to the extending element and add the desired content. This results in adding the new content to the new element that already includes the original content.

The net resutl: A new element that includes the original content plus the new content.