Guideline: Creating Plug-ins, Practices and Configurations
This guideline explains how to name and briefly describe a method plugin.
Relationships
Main Description

Defining Plug-ins

 The following are some general guidelines when defining method plug-ins:

  • Name and briefly describe the plug-in. 
      
  • Capture the source of the information for the plug-in. This information is important if you ever need to provide source information for the plug-in for documenting ownership rights.
        
  • Maintain accurate change histories, as well as making sure your trademarks and copyrights are accurate. 
     
  • Identify any plug-ins that the plug-in must reference (in other words, the plug-ins the new plug-in depends on).
      
  • Define content packages to contain the method elements. Alternatively, those packages can be created on demand, as method elements are defined in the plug-in.

Consider the following when deciding whether or not to create a new plug-in:

  • Don't modify content in plug-ins that are locked or owned by other parties. Instead, create a new plug-in that extends or replaces the base content. Standard plug-ins provided as part of a standard library should be locked to avoid inadvertent changes. Lock any third-party plug-ins after importing them.
  • Each plug-in has a physical file that contains information about all of the other content elements in the plug-in. Therefore, if several individuals are working on content for the same plug-in, that file will need to be carefully controlled. In such cases, you may want to consider dividing the method content that will be added to the base method content into more than one plug-in to avoid contention over the plug-in file.
  • Before defining new plug-ins, be sure to review the structure and content of existing method plug-ins. This is especially important in those cases where you are customizing or building on an existing method.

Defining plug-ins in UMF  

When defining plug-ins that are to exist within the Unified Method Framework (UMF), the practice framework plug-in types need to be considered. These types affect what elements can be placed in what plug-in.  For example, base definitions for practice-specific method elements are defined in Practice Base (or Extend) plug-ins, and base definitions for non-practice-specific method elements are defined in Core Base (or Extend) plug-ins. However, assignments that are delayed are defined in Assign plug-ins.   

In addition, all UMF plug-ins must have a specified copyright (see the topic Copyrights in the UMF below), as well as release information.

Defining Plug-ins using Templates

Method content descriptions can be written using templates.  The resulting documents can then be used to collaboratively complete the content.

This method of method element authoring is appropriate when:

  • A method authoring tool is not being used.
  • There is a need for support for markup and reviews of the content being developed that is not provided in the method authoring tool being used.
  • There is a reason not to have each author use the authoring tool directly for authoring the content (for example, the desire to not have to train all the SMEs to use the tool before they can provide content).

To use templates:

  • Create a template that represents the information you want to capture for each type of method element.
  • Make the templates available to the content authors (e.g., via a customized Method Authoring Method).
  • Complete and review the content for each content element to be authored in this fashion.
  • Once the content has been reviewed and approved, migrate the content into the the method authoring tool.

Once the content in the template has been reviewed and is fairly stable, if a method authoring tool is being used, the content can be migrated to the tool.

Packaging Method Elements

Method packages represent a set of selectable method content elements that provide the user with flexibility in choosing what portions of the method he wants to publish. Method elements in one package can reference elements in another package.

Method packages should be used to represent logical units for useful configurations – sets of elements that should either be included together in a configuration or excluded from a configuration. The user can choose which packages to include in the published site by making selections in the configuration.

Consider packaging very carefully to provide flexibility in what is published. For example, you could put all of the tool mentors for a specific tool into a single content package.  This makes it very easy for someone to deselect the tool mentors from publication.

Packages should be defined so that selecting all packages does not result in overlapping or conflicting content. If alternatives are needed, separate plug-ins should be defined, not just separate packages.

Method packages can also be used to collect obvious categories of content to make it easy to find things, as opposed to just seeing a long list of elements. 

The following sections provide guidelines on the use of the two types of packages: method content packages and process packages.      

Method content packages

There are several organizational strategies that can be applied to refine the method content packaging structure. 

Option 1: Organizing the content packages along the major areas of concern of the plug-in.

When organizing the method content packages of the plug-in along the plug-in's major areas of concern, group all method content that supports a specific area of concern together in the same (or sub-) content packages.

The pros of organizing the content packages along the plug-in's major areas of concern are as follows:

  • It is easy for users configuring the method to select only those areas of concern that they are interested in.
  • The method package structure truly reflects the architecture of the plug-in itself, where each content package is cohesive, but loosely coupled with other packages.
  • A plug-in's content package structure should not be dependent on the base library package structure, which may change at any time.

The cons of organizing the content packages along the plug-in's major areas of concern are as follows:

  • When the plug-in's package structure is not aligned the base library's package structure, it is harder to see what plug-in content packages should be selected when specific base content packages are selected. When the packages are aligned, it is easy to see where the plug-in content fits into the base content.
Option 2: Echo the packaging used in the base plug-in.

In this approach, align the content package with the base plug-ins content packages. Define a content package structure that looks just like the base plug-in's and place the method content elements in the most appropriate package.

If content is contributed to only one or two packages of the base plug-in, rather than to most packages, echo only that portion of the base plug-in structure that is needed. For instance, if the base package \Design\Visual Modeling is the only package modified, echo only the base plug-in packaging structure of \Visual Modeling and its eventual sub-packages.

The pros of aligning the plug-in package structure with the base content's are as follows:

  • When the packages are aligned, it is easy to see where the plug-in contents fit into the base plug-in.
  • It also preserves the package selection choices provided by the base plug-in for publication.

The cons of aligning the plug-in package structure with the base plug-in's are as follows:

  • The plug-in structure does not reflect its architecture, but instead reflects the base plug-in's architecture, which can change at any time.

Method elements that support specific aspects of the plug-in are not packaged together, so it is not easy to select relevant subsets of content to be included in a configuration.

Process packages

Process packages organize processes so they can be managed and located easily. The Configuration View is often used when defining new processes because drag and drop is enabled from this view into the process editors. In this view, plug-in divisions are not shown, so it can sometimes be helpful to define process packages in plug-ins as the process packaging hierarchy for each plug-in is preserved. For example, you may want to put all processes in a plug-in in a process package that is named to represent the plug-in.  If a plug-in has many processes, you may want to define subpackages. 

In most cases, process packages are used for capability patterns only (the number of delivery processes is usually so small, packages are not  needed). 

Defining Method Configurations

This guideline describes how to define method configurations.  Method configurations may be defined for multiple reasons. Some of the most common reasons are to support the construction of processes (process construction configurations) and to support the publishing of the method (publishable method configurations).

Defining a configuration involves identifying the configuration, naming it and briefly describing it. It is also important to maintain accurate change histories, as well as make sure your trademarks and copyrights are accurate.

Defining process construction configurations

Every process must have a default configuration. Thus, some configurations may be defined just to serve as the default configuration for a process, as opposed to being published. Process construction configurations include just those plug-ins that contain elements that are needed to construct the process and no more. They do not have associated navigation views (they are not intended to be published). When naming and describing construction configurations, it is recommended that you include the name of the plug-in containing the processes the configuration is the default for in the name of the configuration.

Defining publishable configurations

Defining publishable configurations is where you think about how you might like to see the elements get published. Which plug-ins should be published together? How many different web sites do you need?  A publishable configuration should be defined for each target audience/variant of the method. For example, if you need a version of the method that focuses on small projects, provide a small projects configuration. If you need a version of the method for more large, complex and formal projects, provide a configuration with more content appropriate to that context. When defining configurations that are intended to be published, try to minimize the size and maximize effectiveness of the published method. Defining configurations is a key part of method authoring. However, selecting the correct set of elements to be included in a configuration can be a difficult and time consuming activity. A few well chosen and high quality elements are worth far more to the end user than a plethora of elements that really don't address the problem at hand. Publishable configurations identify navigation views that are to be published.

When defining a publishable configuration, in the Main description describe the target audience for the configuration and any other relevant details about it. This information is not published; it is intended primarily for the users of method content to decide if they want to use this configuration.

As with all configurations, an important part of defining a publishable configuration is selecting the plug-ins and/or packages that are to be published, as well as specifying those elements that should not be published. 

In addition, the navigation views that are to be published for the configuration should be specified, as well as any publish options.

Defining Practice Configurations

Practice Configurations are an important artifact in a Practice Framework as they assemble a specific set of Practices into something a practitioner can use. When defining the practice configuration, you must adhere to the architecture of the framework in which the configuration is to exist.

Thus, when trying to decide what practice configurations to produce, it is important to take the time to understand the nature of the business problem the practice configuration is intended to solve (the configuration's purpose) and who will be the primary consumers of the configuration (the configuration's intended audience). Understand what the scope of the problem is and the approach to solving it. This understanding forms the basic information that will guide many decisions that will affect the ultimate usefulness of the process configuration. It will also guide you in choosing an applicable name for the practice configuration. 

At this point, its even a good idea to identify practices that will be included in the practice configuration, as well as any cross-practice processes that may be included and what practices they will be assembled from. These are not defined in detail at this stage, but identifying them can help clarify the scope of the practice configuration.

In summary, the following are some key pieces of information that you should capture for a practice configuration and some examples for that information:

  • Name: MAM for Organization X
  • Purpose: Describe the best practices for authoring practice frameworks at Organization X.
  • Scope: All MAM practice framework practices plus Organization X customizations.
  • Intended Audience: Process Engineers at Organization X

Practice configurations are physically represented by publishable configurations. Thus, defining a practice configuration involves identifying, naming and briefly describing that publishable configuration, and including the above information in the definition of the publishable configuration. For more information on publishable configurations, see [Concept: Practice Library Configuration Types]. 

Note: A practice configuration can be defined by mimicking an existing practice configuration. In that case, you can define the new practice configuration by copying components of the original practice configuration, including the existing practice configuration's method configuration and practice configuration-specific Publish plug-in.

Defining Practice Configuration Welcome Page

Every Practice Configuration should have a Welcome page that clearly states the purpose, scope and intended audience for the configuration. 

It is also a good idea to describe, at a high-level, how the practices included in the configuration fit together (remember, a practice configuration is more than just a collection of practices). This high-level description may be in any format, whether that be textual (like a roadmap) or graphical (like an activity diagram, flow chart, capability pattern, etc.). Treat this overview as though it were the introduction to a book (where the practice configuration is the book).  It should give the reader the lay of the land without going into too much detail.

In addition, if the practice configuration includes multiple navigation views, each addressing the navigation needs of a particular type of user, it is usually a good idea to describe what navigation views are available and when you should use one versus the other. 

The Welcome page is also a good place to link to release information for the configuration.

Welcome pages are defined as supporting material guidance elements with a special icon.

Copyrights in the UMF

In the Unified Method Framework (UMF), every plug-in must have an associated copyright (and every plug-in can only have one copyright). 

Copyrights are defined in Release Copyright plug-ins. There is one Release Copyright plug-in per licensing level that contains the copyright elements (defined as supporting material guidance elements) for that level. Every plug-in at a particular licensing level needs to be associated with the copyright for that licensing level. Copyrights are associated to plug-ins as part of the plug-in's definition.

If a specific copyright is needed for a specific plug-in, then perform the following to create a specialized copyright:

  1. Define an Extends plug-in for the Release Copyright plug-in at the licensing level of the plug-in requiring the special copyright.
  2. In the Extends plug-in, define a supporting material guidance element that extends the copyright element for that licensing level. This results in a new copyright element that looks just like the original copyright element that was extended. 
  3. Also in the Extends plug-in, define a supporting material guidance element that contributes to the extending copyright element and add whatever special copyright information is needed. Now you have a specialized copyright that includes the appropriate copyright information for the licensing level plus the special copyright information. 
    Note: The extending element and the contributing element are both needed. If you add the specialized copyright information to the extending element, then that information would override the text in the original base, and in this case, that is not what we want (we want to add the specialized copyright information to the general licensing level copyright information). By using the extend-contributes pair, you can create a new element that includes the same content as an existing element plus more. For more information on method content variability, see the topic Using Method Content Variability in the Guideline: Defining Method Elements.
  4. Associate the specialized copyright to the plug-ins (or individual method elements) that need it (copyrights associated with a plug-in are automatically associated with all elements in the plug-in).