Defining Plug-ins
The following are some general guidelines when defining method plug-ins:
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:
-
Define an Extends plug-in for the Release Copyright plug-in at the licensing level of the plug-in requiring the
special copyright.
-
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.
-
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.
-
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).
|