Guideline: Defining Method Elements
This guideline provides recommendations for identifying and structuring method content elements (e.g., roles, tasks, work products and guidance).
Relationships
Related Elements
Main Description

Defining Method Content Elements

Method content elements are:

Defining a method content element involves creating the plug-in that will contain the element (if it does not already exist), naming the element and briefly describing it. Any issues naming an element and briefly describing it may indicate that the element is not a good element after all.

General Guidelines

The following are some general guidelines when defining method content elements:

  • Reduce the overall number of method content elements (e.g., the number of work products, tasks, roles). Combine similar elements.
        
  • Document process-dependent information separate from the method content element definition. Method content elements should be process independent. Any minor differences/tweaks to the elements based on where they occur in a particular process or lifecycle can be captured in the processes in which the element appears (more on this below). This maximizes the reuse of the method content across processes. For more information on defining processes, see Guideline: Defining and Customizing Processes.
       
  • Start with the work products. When identifying method content elements, its always a good idea to start with identifying the work products. Work products are the manifestation of the solution to the problem the method addresses. They must be clearly understood at the very beginning of a method authoring project. Identifying the work products may appear to consume considerable time but unless they are clearly defined, the project will fail. For more information, see the "Defining work products" section below.   
         
  • Use guidance to supplement the basics and capture details. Guidance elements can be used to supply various kinds of information and assets to method elements so that practitioners are better equipped to execute the work.
       
  • Capture the source of the information for the element. This information is important if you ever need to provide source information for the element for documenting ownership rights.
        
  • Maintain accurate change histories, as well as making sure your trademarks and copyrights are accurate.
  • Reuse existing content. When defining method content elements, it is always a good idea to reuse existing content, both content inside the method being developed, as well as content available externally. This is especially important in those cases where you are customizing or building on an existing method. Many elements may already be defined. It is usually better to start with an existing element than starting from scratch. When reusing an existing element, make sure that the content of the element is what you expect. For more information on how to leverage existing content and maximize reuse between method content elements, see below.
       
  • Use content packages to organize the defined method content elements. When defining method content elements, you may find that you want to introduce some packages in order to better organize the elements. For more information, see Guideline: Creating Plug-ins, Practices and Configurations.

The following sections provide method-element-specific guidelines.

Defining work products

There are three types of work products that can be defined:

  • Artifact – provides a description and definition for tangible, non-trivial work product
  • Deliverable – a collection of work products, usually artifacts
  • Outcome – an intangible work product that may be a result or state.

Following are the guidelines for creating each of these work product types.

Defining artifacts

Artifacts are tangible, well-defined work products consumed, produced, or modified by tasks. Artifacts may be composed of other artifacts.

Artifacts are the responsibility of a single role, making responsibility easy to identify and understand, and promoting the idea that every piece of information produced in the method requires the appropriate set of skills. Even though one role might "own" a specific type of artifact, other roles can still use the artifacts, and perhaps even update them, if the role has been given permission to do so.

Defining deliverables

deliverable is a work product that provides a description and definition for packaging other work products, and may be delivered to an internal or external party. Deliverables are used to represent an output from a process that has value to a client, customer or other stakeholder.

Defining outcomes

An outcome describes an intangible work product that represents a result or state, such as an installed server or optimized network. Outcomes may also be used to describe work products that are not formally defined. 

Defining roles

A role defines a set of related skills and competencies. Roles are used by tasks to specify who performs them.  Roles may be given responsibilities for specific work products. 

The following are some criteria that affect what roles you define in your method:

  • Organization (what are the roles in the organization that the method supports)
  • Type of project (what roles participate in the projects that the method supports)
  • Style of governance (e.g., different RACI matrices)

The smaller the number of roles, the better. Define roles to represent distinct skill sets, things a person may choose to do for a living, as opposed to something that someone may do on the project at any particular point in time using the skills they have with some additional guidance. For example, a person may be an analyst or a designer, but may also serve as a reviewer in some circumstances, or may be responsible for implementing a change request. Thus, "analyst" and "designer" are good examples of roles, where as "reviewer" and "change request implementer" are not as they perform things that anyone can do using their basic skill set (plus some additional guidance like guidelines and checklists).

The following are some criteria that affect how you assign roles to work products and tasks in your method:

  • Work allocation in the organization and/or on the project that the method supports (who does what)
  • Style of governance (make very precise responsibility assignments; e.g., different RACI matrices -- RACI, RACI-VS, VARISC, RASCI)


Defining tasks

A task is a description of a unit of work. The performing role typically transforms the input work products into output work products to achieve a well-defined goal. This description is complete and independent of when in a process lifecycle the work will actually be performed.

Describe tasks in a consistent way, both in terms of naming and in terms of scope/granularity. Try to standardize on a key set of verbs and the way those verbs are used in the task names.

Define tasks so that they are independent of any specific process/lifecycle. Tasks provide step-by-step explanations, describing how specific development goals are achieved independent of the placement of these steps within a specific process (e.g., development lifecycle). Processes take these method elements and relate them into semi-ordered sequences that are customized to specific types of projects. For example, a software development project that develops an application from scratch performs tasks such as "Develop Vision" or "Use Case Design" similar to a project that extends an existing software system. However, the two projects will perform the tasks at different points in time with a different emphasis, i.e., they perform the steps of these tasks at different points of time and perhaps apply individual variations and additions.

When identifying what tasks are needed, it is important to decide on the granularity of the task. In doing so, the following should be taken into consideration:

  • A task generally has only one primary output work product. However, there are instances where more than one work product is worked on simultaneously, so it is possible that you will want to define some tasks that do have more than one output work product.
     
  • It is recommended that you define a separate task for each state change a work product product goes through. Since different states need different checklists, have different completion criteria, and have different execution guidance, it makes sense to have different tasks.
      
  • When the inputs to a task are different, you probably have two different tasks.
      
  • When the task is assigned to different roles, you probably want two different tasks.

You identify a task when there is a need to transform input work products into outputs through a series of steps performed by one or more roles independent of a breakdown structure.

When defining a task, you should also define it's relationships with other method content elements. A task can have the following relationships with other method content elements:

  • Roles:  Two types of roles can be specified:
    • Primary Performer:  Each task should have a primary performer. This is the role this is responsible for ensuring that the task is completed. 
    • Additional Performers:  Additional performers help execute the task. They provide information and expertise.
  • Work Products:  This is where inputs and outputs to the task are identified. Specify:
    • Mandatory Inputs:  Mandatory inputs are the work products the task depends upon for its successful execution. These are the inputs that the task cannot do without.
    • Optional Inputs:  Optional inputs are the work products that provide additional information or context for the task when it is being executed. However, the task does not depend on them for successful execution.
    • Outputs:  The output work products are those that are produced directly by this task. Most tasks will have only one output work product.

Defining guidance

Guidance provides additional details to enhance method content. In fact, methods are more flexible if the content provided in specific method elements is kept as general as possible, with more detail provided as guidance. The method can be easily customized by simply adding or removing guidance. This section provides recommendations on how to define guidance and how to associate the guidance with other method elements. 

There are many different types of guidance, all designed for specific purposes. The guidance types are:

  • Checklist – identifies a series of items that need to be completed or verified. Checklists are often used in reviews such as walkthroughs or inspections. Checklists may also be a series of questions or a script that practitioners may use to lead a discussion with the client's personnel. This might take the form of a questionnaire or interview outline that focuses on the information needed for the work product or deliverable. In UMA, a content element has at most one checklist. Checklists are useful in a number of contexts: they help in deciding what to do, they help doing it, they help assess the quality of the work, and they help understand how a particular work product relates to the rest of the process.
    It is recommended that checklists only be associated with work products and not tasks. If a checklist is needed for a task, then it can be accessed via the work products associated with the task.
    In general, checklists do not require a brief description. However, if there are multiple checklists for a method element, a brief description is helpful to distinguish between them.
       
  • Concept – outlines key ideas, basic principles and motivations underlying a topic central to the method. Concepts normally address more general topics than guidelines and may span several work products, tasks, activities, or disciplines. Examples of concepts might be In the context of risk management, performance testing, implementation planning.
       
  • Example – a sample instance of a partially or fully formed work product or deliverable. The instance may contain live client data (with the client's express permission to use it) or it may contain fabricated data that is representative of the information required for the engagement. However, this example is necessarily generic and is only a guide to what might be required in an actual work product or deliverable for a specific engagement.
      
  • Guideline – provides additional details, "how to" information, alternatives, recommendations, or rules about the use of a content element. For example, a work product typically has guidelines associated with it that provides information on how to develop, evaluate, and use it. Guidelines can provide the context in which a work product or other content element exists within a method. A guideline helps practitioners understand how a particular content element is used and how it relates to the rest of the process in which it exists. This includes formal technique papers for developing work products and deliverables.
       
  • Estimation Considerations – guidance on how to estimate the use in a project of the element with which it is associated. The guidance may be textual, a spreadsheet, tool, or take some other form.
      
  • Practice – a proven way or strategy of doing work to achieve a goal that has a positive impact on work product or process quality. Practices are defined orthogonal to methods and processes. They could summarize aspects that impact many different parts of a method or specific processes. Examples for practices would be "Managing Risks", "Continuously Verifying Quality", "Architecture-centric and Component-based Development", and so on.
        
  • Report – a predefined template of a result that is generated on the basis of one or more work products as an output from some form of tool. A report is not an artifact in itself. It is, in most cases, a transitory product of a process or monitoring, and a vehicle to communicate certain aspects of the evolving system; it is a snapshot description of artifacts that are not documents themselves.
        
  • Reusable Asset – a type of guidance that references assets that lie outside the method. These assets may be too large or volatile to be embedded. These assets may also be third party products or services for which usage permission has been granted by the owner.    
      
  • Roadmap – represents important documentation for the activity or process it is related to. Often a complex activity such as a process can be much more easily understood by providing a walkthrough with a linear thread of a typical instantiation of this activity. In addition to making the process practitioner understand how work in the process is being performed, a roadmap provides additional information about how activities and tasks relate to each other over time. Road maps are also used to show how specific aspects are distributed over a whole process providing a kind of filter on the process for this information.
        
  • Supporting Material – this is a catch-all for assets that do not fit in another type.
        
  • Template – a version of a work product or deliverable instance that does not contain data so that the practitioner may use it to "fill in the blanks". This is usually a form or set of fields that define the data to be collected and may assist in analyzing the data to produce the information for the completed work product or deliverable. Taken together the example and the template form a powerful pair for the practitioner. In the first, the practitioner sees a completes or partially completed work product while the second offers a convenient means of producing the work product as rapidly and as accurately as possible.
       
  • Term Definition – a definition of a word or phrase that is not in the glossary and that practitioner need to understand for the method plug-in.
       
  • Tool Mentor – a description of how to achieve certain goals with a specific tool. Tool mentors link tasks with tools such as IBM® Rational® Method Composer. They almost completely encapsulate the dependencies of the content on the tool set, keeping the tasks free from tool details.
      
  • White Paper – an externally published paper that can be read and understood in isolation of other content elements and guidance

Guidance should be written with a specific scope in mind.  For example:

  • Guidance can be more general, written with regards to a set of elements (e.g., workshops, collaboration, lifecycle families, etc.)
  • Guidance can be method-element specific (e.g., written regarding a specific work product, task, role, process) , or

The name of a guidance element should reflect that scope. Specifically, method element-specific guidance should include the method element name in its name. For example, Guideline: Detailing a Use Case, Template: Use-Case Template.

Guidance may be attached to any method element and guidance should be attached to method elements, as needed. However, decreasing the number of relationships defined between elements in the method helps to reduce the overall perceived complexity of the method. In general, guidance should be associated with the smallest number of elements possible. Having "everything associated with everything" is a bad idea as it directly affects the usage of the published web site.
For example, avoid associating the same guidance with work products and tasks that produce the work products as this creates unnecessary dependencies since the same content will be linked in via one of the other relationships anyway. 

Guidance should be associated with the element that reflects its scope (i.e., the element where the end-user would be expected to look for it).  Method element-specific guidance should be associated with the method element it describes:

  • If the guidance is about notation or representation of a work product (e.g., template, example, checklist) then it should be associated with the work product
  • If the guidance describes a specific technique about how to produce the work product then it should be associated with a task that produces the work product
  • General guidance should be associated with "general" elements (e.g., slots, standard categories, reference workflows, etc.) or possibly just included in custom categories (aka navigation views)
  • Roles are not a common place for associating guidance, unless that guidance is specific to the role (and not to a task the role performs or a work product the role is responsible for)

Most guidance should be associated with at least one element. Of course, there are exceptions:

  • Guidance that is about the method, as opposed to being part of the method (e.g.,  Welcome pages, About pages, What's new pages, etc.). Such guidance is usually only referred to from navigation views.
  • General guidance (e.g., concepts, white papers) sometimes need to be associated with "general" elements. 
    Some possible associations for general concepts are associating to them from standard categories, custom categories/navigation views, etc.

When defining guidance elements, you must constantly weigh reuse concerns versus complexity:

  • If you define fine-grained guidance elements, then you can assign the guidance elements to specific method elements, which provides just the guidance you need, but then you have many guidance elements, which can be construed as being more complex). 
  • If you define course-grained guidance elements, then have a smaller number of guidance elements, but then the same guidance elements is attached to multiple elements and you have to find what you are looking for by scrolling through the course-grained guidance element.

Make the best choice based on your circumstances and let end-user feedback be your guide. 

Roles in the UMF

The Unified Method Framework (UMF) defines some constraints with regards to the definition and use of roles and role sets. 

The UMF implements a delayed role assignment approach, which means that the assignment of roles to method content elements is NOT done as part of the definition of the method content elements.  In addition, in the UMF, role definitions are intended to be shared.  Thus, in the UMF, the roles and role sets are defined separately from the method content elements they can be assigned to (e.g., work products and tasks), as well as from the assignments themselves. Roles and role sets may be shared across practices or may be practice-specific and this decision affects what plug-ins their definitions and assignments are placed.

Shared roles and role sets:

  • Shared roles and role sets are defined in a Role Definition Base plug-in. 
  • Shared roles are assigned to shared role sets in a Role Definition Base plug-in. 
  • Shared roles are assigned to tasks and work products in the Assign plug-in associated with the Base plug-in where the element to be assigned to the role (work product or task) is defined. 

Practice-specific roles and role sets:

  • Practice-specific roles and role sets are defined in the Practice Assign plug-in.
  • Practice-specific roles are assigned to practice-specific role sets in the Practice Assign plug-in. 
  • Practice-specific roles are assigned to tasks and work products in the Practice Assign plug-in. 

The benefits to the UMF approach to roles are:

  • Roles and role sets can be shared across practices (shared Role Definition plug-ins)
  • Alternate role assignments can be defined (provide alternate Assign plug-ins)

Note: If you are developing a method where the role assignments can NEVER change, then late role assignment is overkill and the role assignments can be done directly in Base plug-ins.


Scaling Method Elements in the UMF

When there is a need to scale, you need to define a base plug-in (or plug-ins) that have a scope generic enough to be scaled. For example, we define an open source core plug-in (or plug-ins) that may have a scope that is broader than OpenUp Basic in open source layer. OpenUp Basic could then be built on that open source core (as would the rest of the IBM methods), possibly using only a subset of the elements in the core. That way, users can have access to the OpenUp Basic content, as well as the broader open source core that is built to be scaled up.

Example of using packaging technique to scale

  • Scaling by adding techniques

    Sometimes we want to offer a specialized technique or alternative technique from which the user can pick and choose. You can either package the technique in a separate technique plug-in or package the technique in its own content package.

    • Create a Technique Plug-in
      • This method is nice because it captures all the work products, tasks, etc, across all disciplines in one place.  Selection of the technique is simply a matter of choosing the plug-in.
      • Alternative techniques can be offered using multiple plug-ins
      • Document restrictions in the Plug-in description (available in the configuration editor) for which techniques can be used together and which cannot.
    • Create a Content Package
      • This method is useful for small, isolated techniques
      • Note: avoid creating dependencies on content package selection (eg, must choose two or none).  If the user will need to select multiple content packages to properly choose the technique, it would be better to use a technique plug-in instead.
  • Scaling by adding resource plug-ins

    Isolating resources, such as examples and templates, to their own plug-in allows users to select which set of resources they want. For example: cmr.res.sw_dev.formal, cmr.res.sw_dev.informal.

    Don't worry about elaborate content packaging of templates: assume that errors in configurations caused by templates not having a WP home because the package containing the WP was deselected.

    Note:  When you have more than one template for a particular work product:

    • If the content of the templates is the same, just the format is different (eg, letter, A4, MS Word, HTML), then you can just add the additional template to the same template guidance element.

    • If the content of the templates is different, then use another Template guidance element to attach the second template.

Common guidelines on scaling

  • Tasks, activities, and steps should be used to describe actionable elements.  Do not add tasks, activities, and steps to amplify "how" a need should be satisfied. That is "guidance" not "work".
  • Resist the temptation to artificially increase the number of actionable items. Project Managers will simply not entertain a work structure with 1100 elements.
  • Use activities, tasks, and steps to define a work road map and put road signs up about the work.  Keep the guidance in the guidance.
  • Define base elements very generically, with add-on concepts that describe where more detailed elements fit in. Example:  describe that DB design is part of design and is covered in design elements, even though separate elements are not defined.

Scaling guidance elements in the UMF

The following sections describe some strategies for scaling guidance elements.

Strategies for scaling guidance
  1. When the content of an existing guidance method content element can be reused in a higher layer, contribute more detail to the existing guidance.
  2. If the content of an existing guidance element cannot be reused in the higher layer, replace the guidance with more appropriate and elaborate guidance.
Strategy for scaling checklists

You can contribute additional items to the list

Strategy for scaling templates

You can contribute additional templates, but it's probably better to create a different template guidance altogether, rather than add different template formats to the same one.

Scaling roles in the UMF

This guideline describe some strategies for scaling roles. For example, in one context, you may have one role set and a few roles. At the next level, single roles may become role sets comprised of multiple roles. Scaling roles is much easier as a result of UMF's delayed role assignment approach, which supports the easy definition of alternate role and role set definitions and assignments. For more information, see the topic above Roles in the UMF.

Scaling tasks in the UMF

The following sections describe some strategies for scaling tasks.

Strategy 1: Packaging

Consider the following:

  • Package generic tasks (ie, a that task includes no details) in a sub-package of the work product it produces
  • Package specific tasks in your context. For tasks that are likely to need to be ‘split' later, package them in their own package.
Strategy 2: Add guidance

Rather than creating more tasks, consider adding more specialized guidance to explain the detail of specific tasks.

Strategy 3: Contribute steps to a task

You can add a step between steps or at the end of the base task steps.  You cannot add to the wording of a particular step.  For example, if you add a new sub-work product to the work product, you can contribute a new step to create the sub-work product.

Tactical Workaround: When you really want to add to a particular step, indicate you are providing a specialized step by naming your step the same as the one you wanted to append to and adding a qualifier in brackets: eg, "Determine how elements collaborate [UML modeling]"

Strategy 4: Create new tasks

Create a new task when: a new role performs the task, it is a unit of work that should be tracked (ie, want it in the WBS), it has different inputs or outputs.

Strategy 5: Suggest a change to the base task 

You could suggest a change to the tasks in the base (eg, OpenUP), so that the base task becomes something you can scale from.  For example, suggest that the text be updated to only describe what is done, not how.

Strategy 6: Make a task an activity and its steps become tasks

Currently, RMC Tool cannot support this strategy.

Tactical workaround:

  1. Deselect the package containing the task you are splitting (if it's not in a separate package, put it in a separate package)
  2. Create the new tasks
  3. Create a Process Pattern (activity) with the same name as the base task
  4. Add the new tasks to the activity
  5. Reconstruct relationships that were to the task to the appropriate new tasks

Scaling work products in the UMF

The following sections describe some strategies for scaling work products.

Strategy 1: Use the notion of container work products in the base.

The base layer (the open source layer) includes a generic work product that can be used as the container for several work products in lower levels. Scale by creating child work products of the base container. Contribute to the base work products when possible, to reinforce the scaling connection, you could add text to say: " For details about WPx see <hyperlink to added WPx>".

Note:  You may need to suggest a change to the base work product to make it more scalable.

Example of Scaling Work Products

Figure 1: Example of scaling "Design" Work Product using the notion of container technique

Figure 1 shows example when scaling up design from the open source layer. In the open source layer, the primary work product is Design. Design is scaling to include conceptual design, logical design, operational design, subsystem design, etc... in the commercial layer. Scaling to the commercial layer, the open source Design sub-WP is reused for small projects (assuming some content proposals are accepted). For medium and large projects, content is contributed to the Design work product which becomes a container for added sub-work products. Again, the licensable layer will reuse commercial layer work products with some content contribution to the Design container work product.

Guideline: Use the most specific work product as input and output that makes sense

Note: Extension is generally not a useful feature because too many associations are kept.

Strategy 2: Split a work product into two
  1. Before attempting to split a work product, consider recommending a change to the base layer to add the work product you need
  2. Define a custom category that contains the work product to remove and select that category in the do not publish part of the configuration.
  3. Create the new work product(s) and include them in your configuration.
Strategy 3: Adding new work products

If you cannot scale using strategy 1 or 2, create a new work product. However, avoid just adding work products. Where possible, try to consolidate them under a container work product or consider whether the open source layer should include the work product.

Note: If you just cannot scale from a work product in the base layer, you may need to suggest a change to the work product in that base (eg, suggest that the description be made more generic).

Tool Information in the UMF

Tool information can come in many forms: tools, tool mentors, examples, templates, supporting materials, capability patterns, white papers, etc.

In the Unified Method Framework (UMF), tool information is defined in multiple plug-ins.

Tools (the standard categories) are defined in the Core in a Tool Definition Base plug-in where they can be shared between Practices.

Other tool information is defined according to its scope:

  • General tool information (as opposed to practice-specific tool information) is defined in the Tool Definition Base plug-in.
  • Practice-specific tool information is defined in the Practice Base (or Extend) plug-in. 

The UMF does NOT implement a Delayed Assignment approach for tools because the assignment of tool mentors to tools does not change (tool mentors are written for a specific tool). Thus:

  • Tool guidance is assigned to tasks in the Practice Base (or Extend) plug-in where the task is defined. The assignment is done directly in the task definition.
  • Tool mentors are assigned to the appropriate Tool standard categories in the plug-in where the tool mentors are defined. The assignment is done by defining a contributor to the Tool standard category (defined in a Tool Definition plug-in) and then assigning the tool mentor to the Tool in the contributor. 

Work Product Slots in the UMF

In the Unified Method Framework (UMF), Work Product Slots are defined as artifacts in Slot plug-ins.  When authoring work products slots, be aware that the content cannot be practice or technique specific. Work product slots are intended to be generic. Thus, the most important thing to document is the information the work product slot represents, not its specific representation or the technique use to develop it.

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 variability element are included 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


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:

  1. Define a method element that that extends the original base element. This results in a new element that looks just like the original element.
  2. 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 result: A new element that includes the original content plus the new content.