Guideline: Architecting a Method Library
This guideline provides recommendations for architecting a method library. This includes sketching a method library, structuring elements in a practice framework architecture, and defining work product slots.
Relationships
Related Elements
Main Description

Sketching a Method

Sketching a method is all about brainstorming about what the method should contain and how it should be organized. 

Sketching is usually performed in a team environment in the context of a series of brainstorming sessions involving method SMEs.

When sketching a method, it is important to identify the key method elements and their relationships, as well as an early draft of a brief description. The key method elements may include any or all of the following:

  • Key content areas, especially if the method is large, and these may evolve into domains and disciplines.
  • Key method content elements and their relationships: what work products are produced and what roles are responsible for them?  What work products are consumed by the process (e.g., what are the input work products)?
  • Key activities: What activities are performed to produce the work products, what work products do those activities produce and consume?
  • Overall lifecycle and milestones. What is the overall lifecycle that you are trying to represent, organized by key milestones and milestone criteria?

When sketching a method, it is important to leverage as much existing content as you can, both from the current context, as well as from existing methods. This is especially important if the ultimate objective is to customize an existing method for the current context.

The following describes an approach for sketching a method:

  1. Identify key work products. Sometimes starting with the key work products can be easiest, as this gives you a set of terms to start working with. What are the key work products that are produced? Provide a brief description that indicates their purpose and key contents. If the work products have significant state, it is a good idea to capture that, as well. In addition to the work products that are produce by the method, it is important to identify work products that are consumed by the method. What are the inputs to the method? What is their expected contents? Can they be refined in any way, or should they be treated as input only?
  2. Identify key activities. Once you have an initial list of work products, you can turn your attention to the key activities that are performed and how those activities produce/consume the work products. If they produce or refine a work product, what is the work product's resulting state after the activity is complete?
  3. Identify key roles. You can also start thinking about what key roles that participate in the process, what work products they are responsible for and any key activities they participate in.
  4. Outline overall lifecycle, including key milestones. Once you have an idea of the key activities, you can start to organize them into an overall lifecycle. First identify the key milestones and describe the milestone criteria in terms of the work products produced and their state. You can then map the identified activities to the milestones they support (i.e., the activities that support the reaching of the goal of the milestone). This may result in additional activities. At this point, don't worry too much about individual tasks, just capture the overall lifecycle in terms of milestones, key activities and their affect on key work products.

Applying the above approach results in a high-level definition of an end-to-end process, including work products, roles, activities, milestones and overall lifecycle.

Sketching a Practice

When sketching a practice, you must first name and briefly describe the practice.  Then identify the practice's relationship with other practice and with other method framework elements.  Specifically, identify what work product slots will provide the inputs to the practices what the practice will produce in terms of work products and what work product slots those work products will fill.  In addition you may want to identify any known guidance that will be shared.

Once you have an understanding of how the practice fits into the method framework, you can turn your attention to what the practice needs to contain (method content and/or process) and the relationships between these practice elements.  If known, it is also a good idea to identify where the content will come from so decisions can be made about the development of the practice.

Structuring a practice is where the elements of the practice and their relationships are defined. Specifically, structuring a practice involves:

  • Defining the practice -- where the practice fits in the overall practice framework and what are its external dependencies
  • Defining the practice elements -- what elements are contained within the practice and what are their relationships
  • Categorizing the practice elements into standard and custom categories

Each of these topics are described in the following sections.

General practice structuring guidelines

The practice structure must be developed within the guiding principles and constraints of the practice framework in which the practice resides.

When structuring a practice, resist the temptation to enter detailed descriptions into the defined method elements. Instead, just name and briefly describe the elements and enter a few outline details, if they help to more clearly describe the element's basic definition. For more information, see the topics Method Element Naming Conventions and Writing Brief Descriptions in the Guideline: General Naming Conventions.

When structuring a practice, be sure to look for opportunities to leverage existing information in core elements and/or in other practices. If you find existing method elements in another practice that you would like to share, work with the method architects to get the common information moved to the core where it can be shared. Likewise, method elements should be defined to maximize reuse. If while structuring a practice you define an element that can be shared across practices, it should be defined in in the core where it can be shared, instead of in the practice. 

Develop a Proof-of-Concept

The proof-of-concept of a method content should be done using the implementation environment you plan to use to author the actual method. That way you can test the technical feasibility of your architectural ideas in the actual implementation environment.

The following are some things that you may want to test out:

  • Your proposed library structure, including the types of plug-ins you are considering creating, their relationships and the types of configurations you are considering creating.
  • Strategy for defining navigation views, identifying any common navigation elements that you may want to share between views and configurations.
  • Strategy for handling copyrights and release information.

As you develop the proof-of-concept, it is important to document any issues and risks that you encounter so that these can be addressed when more formally defining the method.

When developing an proof-of-concept for a practice framework, be sure to include a set of practices, some interfaces between those practices (e.g., work product slots), as well as some configurations representing the method configurations those practices will be included in. You may also want to take into consideration any defined plug-in types and/or configuration types. 

Structuring the Practice Framework Core

Structuring the Practice Framework core is where the core elements of the framework and their relationships are defined. The core structure must be developed within the guiding principles and constraints of the practice framework in which the core resides.

When structuring a practice, resist the temptation to enter detailed descriptions into the defined core elements. Instead, just name and briefly describe the elements and enter a few outline details, if they help to more clearly describe the element's basic definition. 

When structuring the core elements, be sure to look for opportunities to leverage existing information in other core elements (for example, core elements for a specific context may extend, customize and reuse elements from a more general core). If you find existing core elements in another context-specific core that you would like to share, work with the method architects to get the common information moved to a more general core where it can be shared. Likewise, core elements should be defined to maximize reuse. If while structuring the core elements for a specific context, you define an element that can be shared across contexts, it should be defined in in a more general core where it can be shared. 

Core elements are physically packaged in Core plug-ins. For more information on Core plug-ins and what elements should be placed in what plug-ins, see [Concept: Practice Library Plug-In Types]. For more information on defining plug-ins, see the topic Defining Plug-ins in the Guideline: Creating Plug-ins, Practices and Configurations.

Structuring the core elements involves:

  • Defining the Work Product Slots. For more information, see the topic Defining Work Product Slots below.
  • Defining the common method content elements and their relationships (including shared roles, work products and guidance). For more information, see the "Defining the common method content elements" section of this guideline.
  • Defining the shared standard categories (e.g., domains and disciplines). For more information, see the "Defining shared standard categories" section of this guideline. 
  • Defining the shared custom categories (including shared navigation views). For more information, see the "Defining shared custom categories" section of this guideline.

Additional information on defining these core elements is provided in the following sections.

Defining a work product slot

Work Product Slots are defined when you need to pass information between Practices. They are defined in Core plug-ins where their definition can be shared.

Work product slots are implemented as work products. However, they are "special" work products in that they are implementation/representation agnostic. Thus, for general information on defining work products, see the topic Defining Method Content Elements in the Guideline: Defining Method Elements.

It is important to remember that work products slots are not "real" elements, in the method sense. Thus, there are some additional authoring guidelines:

  • Work product slots may appear as inputs to tasks
  • Work product slots may not appear as an output to tasks
  • Work product slots are filled by real work products in specific practices  
  • Work product slots should not be categorized using standard categories
  • When naming separate work product slots, use a descriptive name that indicates explicitly that the element is a slot. Specifically, the slot's presentation name should be between brackets and it's internal name should end in ("_slot").  Such conventions make it easy to see what is a slot and what is an actual artifact that fills a slot. 
    For example:
    • Presentation Name: [Specified System]
    • Name: specified_system_slot

Defining the common method content elements

In a practice framework, the common method elements usually include common roles definitions, work product definitions and guidance. Tasks are not considered common elements (they defined in specific practices).

The following sections provide core-specific recommendations for defining the common method content elements. For general guidelines on defining method content elements, see the topic Defining Method Content Elements in the Guideline: Defining Method Elements

Defining common work products

Work product definitions are provided in core to allow practices to share the common definition, even though they may use the work product differently (e.g., provide different techniques for producing and consuming the work product).

Work products are not specified as fulfilling specific slots in the core. The fulfillment of slots is defined within the practice (not in common). 
Note: Even though common work products are defined in Core, they do not really "exist" as part of the method being defined until they are placed in a slot by a practice. In that case, the work product is considered conceptually part of that practice. The only reason these work product definitions are physically placed in the core is so their definition can be shared. 

Work products in the core are generally "state free". Specific work product states are considered practice-specific information.

Work products in the core do not have an associated responsible role. What role is responsible for what work product is a practice-specific decision.

Defining common roles

Practice frameworks generally implement a Delayed Assignment approach for roles and role assignments so the role definitions and/or assignments can be easily changed. Common role definitions are included in the core, but they are not assigned to work products or tasks. These assignments are defined as part of the practice.

Defining common guidance

Common guidance is guidance that can be shared across practices. Such guidance is not associated to any method content elements in the core. Such associations are done as part of defining the practice.
Note: Even though common guidance is defined in the core, such guidance is considered conceptually part of the practice where the guidance is associated to specific practice elements.

Defining shared standard categories

Standard category definitions (domains, disciplines, work product kinds, role sets, tools) are are generally shared across practices, so they are defined in the practice framework core. However, practice frameworks generally implement a Delayed Assignment approach for standard categories, except for tools (since what tool mentors are assigned to what tools usually does not change). Thus these categories are defined in the core, but elements are not categorized using these categories in the core. The categorization happens as part of the practice. For more information on categorizing method elements into standard categories, see the topic Categorizing Method Elements Using Standard Categories in the Guideline: Categorizing.

Defining shared custom categories

Custom categories may be defined in the core that can be shared across practices. A common example of a shared custom category is a navigation view, but other custom categories may be defined, as well.

Elements are added to the shared custom categories in the core and in practices, as desired. For more information on categorizing method elements into custom categories, see the topic Categorizing Method Elements Using Custom Categories in the Guideline: Categorizing.

These custom categories can then be included, as desired, as part of publishable method configurations. For more information on publishable configurations, see [Concept: Practice Library Configuration Types]. 

Customizing Practice Framework Core Elements

Practice Framework core customizations are stored in a separate plug-ins from the core elements being customized. Specifically, all core element customizations should be defined in an Extend plug-in for the Core plug-in that contains the element to be customized. For more information on Core and Extend plug-ins, see [Concept: Practice Library Plug-In Types].

There are a number of different ways that you can customize the practice framework core. You can: 

  • Add a new work product slot
  • Customize an existing work product slot
  • Add a new common method content element (e.g., role, work product or guidance; tasks are generally stored in Practices) 
  • Customize an existing common method content element 
  • Add new shared domains or disciplines
  • Customize existing shared domains or disciplines

The following sections describe how you would structure these customizations. 

Add a new work product slot

Perform the following steps to define a new Work Product Slot:

  • If it does not already exist, create an Extend plug-in to contain the new slot.
  • Define a new artifact and indicate that it is a slot.

Customize an existing work product slot

Perform the following steps to customize (not just by adding guidance) an existing Work Product Slot:

  • If one does not exist, create an Extends plug-in to contain the slot customizations.
  • Customize the slot the same way you customize any work product. However, since slots are shared across practices, be sure that they adhere to guidelines for slots and that the changes are applicable across practices. For more information on customizing work products, see the topic Customizing a Method Content Element in the Guideline: Defining Method Elements.  

Add a new common method content element

Perform the following steps to add a new common method content element (e.g., role, work product, guidance) to the core (tasks are generally not common, but are considered practice-specific): 

  • If it does not already exist, create an Extend plug-in to contain the new common element.
    Note: Practice frameworks generally implement a Delayed Assignment approach for roles, so it is recommended that role definitions be placed in their own plug-in.
  • In the new plug-in, define the new element. These elements are common so be sure to only include information that is common across practices. Do not include any associations between elements as such relationships are better-defined in practices. For more information, see the topic Defining Method Content Elements in the Guideline: Defining Method Elements.

Customize an existing common method content element

Perform the following steps to customize an existing common method content element (e.g., role, work product, guidance) to the core (tasks are generally not common, but are considered practice-specific):

  • If one does not exist, create an Extends plug-in to contain the customizations.
  • Customize the elements the same way you customize any element. However, since common elements are shared across practices, be sure to only include information that is common across practices. Do not include any associations between elements as such relationships are better-defined in practices. For more information, see the topic Customizing a Method Content Element in the Guideline: Defining Method Elements.  

Add a new shared domain or discipline

Perform the following steps to add a new shared domain or discipline:

  • If one does not exist, create an Extends plug-in to contain the domain or discipline definitions.
    Note: Practice frameworks generally implement a Delayed Assignment approach for standard categories, so it is recommended that domain and discipline definitions be placed in their own plug-in. 
  • In the new plug-in, define the new standard category. Do not assign any elements to the categories as the categorization of elements to standard categories is done in the practices.

Customize existing shared domains or disciplines

Perform the following steps to customize and existing shared domain or discipline:

  • If one does not exist, create an Extends plug-in to contain the domain or discipline customizations.
    Note: Practice frameworks generally implement a Delayed Assignment approach for standard categories, so it is recommended that domain and discipline definitions be placed in their own plug-in. 
  • In the new plug-in, customize the standard category. Do not add any elements to the categories as the categorization of elements to standard categories is done in the practices.

Documenting the Practice Framework Architecture

Documenting the architecture of a Practice Framework is critical to making sure that key decisions are captured and communicated to the development team. Documenting the practice framework architecture involves defining and capturing the key guiding principles and a consistent approaches for structuring the framework, as well as documenting the key structural elements. 

In general, don't spend much time:

  • getting the architecture perfect -- it can evolve over time as the individual method elements are defined and detailed. 
  • providing detailed descriptions of the method elements -- just name and briefly describe the elements and enter a few outline details if it helps to more clearly describe the element's basic definition.

Note: While documenting the architecture is important, it is not enough to just define it on paper. It is important that the architecturally-significant method elements be actually built using your selected method implementation environment.

When documenting the architecture, there are two key decisions that you need to make: what to include in the architecture description and what level of detail. Each of these are described in the following sections.

Architecture content

The architecturally-significant method elements in a practice framework are the following:

  • Practices
      
  • Core elements: Elements shared across practices:
    • Work Product Slots: Information that passes between the practices,
    • Common method content elements (especially, roles, guidance, work products) such as the definitions that are shared across practices,
    • Common standard categories (especially domains, disciplines, work product kinds, role sets, tools),
    • Common custom categories.
       
  • Practice Configurations: Assemble practices into usable methods for practitioners

The following are some examples of the types of decisions you might make (and document) when architecting a method framework:

  • Use a Delayed Assignment approach for role assignments and standard category assignments (except for tools) in order to improve the flexibility and ability to configure the framework
  • Use a specific set of method plug-in and method configuration types in order to provide a consistent approach for structuring the framework. We recommend the plug-in types defined in [Concept: Practice Library Plug-In Types] and the configuration types defined in [Concept: Practice Library Configuration Types].
  • Follow a consistent set of naming conventions. We recommend the ones defined in Guideline: General Naming Conventions
  • Provide recommendations and constraints for the following:
    • How navigation view should be built
    • How standard categorization should be handled (as well as any common standard categories)
    • Approach for assigning roles (as well as any common roles)
    • Approach for scaling elements
    • Approach for associating guidance
    • Approach for dividing the architecture into smaller chunks to reduce complexity

Level of detail

There is a range of options for the information that can be captured in an architecture description. In some cases, where there is an architectural decision to be made, there are a set of architecture notes that are written up proposing what to do, discussing all the choices and the tradeoffs that have been made. These notes can be an email thread, a forum thread, or a Wiki. Then, the final decision is captured in an architecture document. The notes serve as a historical record of decisions (if you keep them) and not a polished, maintained view of the architecture. The maintained architecture document is a separate work product that is mainly targeted at new developers and maintainers of the system, and to ensure the architecture does not degrade. The notes get filed in a notebook for later reference in case people are curious why the team did something.

In summary, the following are the range of options for the architecture documentation:

  1. Keep a set of notes that are a historical collection of architecture notes that are not maintained
  2. Keep a set of notes, plus define a high-level overview of the architecture
  3. Keep a set of notes, an architectural overview, plus a set of distilled key decisions
  4. Keep a set of notes, an architectural overview, a set of distilled key decisions and a set of evolutionary models
  5. Keep a set of notes, an architectural overview, a set of distilled key decisions and a set of formal models at different levels of abstraction

For each project, it is important to decide which of the above options makes the most sense.