Guideline: Categorizing |  |
This guideline provides recommendations for categorizing method elements using standard categories and custom categories.
Main Description
### Categorizing Method Elements Using Standard Categories Standard Categories provide a means to categorize core method content in line with the best practices for creating structured methods. Standard Categories are linked to a specific method content type. The Standard Category types are: Disciplines A discipline is a category of tasks that are related to a major area of concern within the overall IT environment. A task can belong to only one discipline. For example, on a software development project, it is common to perform certain requirements tasks in close coordination with analysis and design tasks. Separating these tasks into separate disciplines makes the tasks easier to comprehend. Disciplines can be organized using Discipline Groupings. Initial recommendations are to develop separate discipline groupings for each major context and standardize on the set of disciplines within that context, allowing for overlap between contexts where appropriate. While disciplines may have many similarities to domains for some areas, no formal relationship between the two has been defined. Disciplines are currently intended to be independent of role sets. In general, the following are some criteria that affect how you assign tasks to specific disciplines in your method: Number of tasks: The more tasks you have, the more there is a need to organize them into disciplines Published representation of the method: How do consumers of the method want to see the tasks organized; define disciplines for those organizational elements Governance: How the tasks are governed; define separate domains for tasks that are governed differently Processes can also be associated with disciplines as Reference Workflows. Note: In some cases, the disciplines and domains are the same (i.e., the same set of names is used for both). This approach minimizes the number of different ways you categorize things, which some see as an advantage. Domains A domain is a refineable, logical, categorization of related work products grouped together based on timing, resources, or relationship. While a Domain categorizes many work products, a work product belongs to only one Domain. Domains can be further divided into sub-domains. Domains are seen by some to be more context-neutral than disciplines (i.e., disciplines tend to be more context-specific). It is recommended that only parent work products be mapped to a domain, not child work products. This will yield a more pleasing tree structure in the published web site because child work products will only show up under their parent. If child work products are assigned to a domain, then they will also be displayed in the tree view at the ‘top level' under the discipline, as well as under its parent. In general, the following are some criteria that affect how you assign work products to specific domains in your method: Number of work products: The more work products you have, the more there is a need to organize them into domains Published representation of the method: How do consumers of the method want to see the work products organized; define domains for those organizational elements Governance: How the work products are governed; define separate domains for work products that are governed differently Note: In some cases, the domains and disciplines are the same (i.e., the same set of names is used for both). This approach minimizes the number of different ways you categorize things, which some see as an advantage. Work Product Kinds A work product kind is another category for grouping work products. A work product can have many work product kinds. As an example, you might want to have a series of work product kinds that correspond to the overall intent of work products, such as specification, plan, or model. The use of work product kinds is optional. In general, the following are some criteria that affect how you assign work products to specific work product kinds in your method: Type of work product: Different work product kinds can be defined for artifacts vs outcomes Number of work products: The more work products you have, the more there is a need to organize them into work product kinds Published representation of the method: How do consumers of the method want to see the work products organized; do they want to see an alternate organization for the work products, in addition to the domain organization. Define role sets for those organizational elements.. Work product kinds are usually more general than domains and usable across contexts. Role Sets A role set is used to categorize roles with certain commonalities together. For example, in a software development environment, an Analyst role set could be used to group together roles such as Business Process Analyst, System Analyst and Requirements Specifier. Each of these roles work with similar techniques and have overlapping skills, but may be responsible for performing certain tasks and creating certain work products. Role sets can be organized using role set groupings. In general, the following are some criteria that affect how you define role sets and how you assign roles to specific role sets: Number of roles: The more roles you have, the more there is a need to organize them into role sets Published representation of the method: How do consumers of the method want to see the roles organized; define role sets for those organizational elements Governance: How the roles and role sets are governed; define separate role sets for roles that are governed differently Tools A tool is a category for tool mentors. Tools can also provide general descriptions of a tool and it's general capabilities. You should define a standard category any time you have a need to categorize method elements. Multiple levels of categories are possible, but you should only define what you need to manage your method content. For example, if your method only contains two tasks, do you really need a discipline? An important part of defining an element is naming it. For recommendations on naming standard categories, see topic Method Element Naming Conventions in the Guideline: General Naming Conventions. You may also want to capture guidance on how to decide what tasks belong in the discipline in the Key considerations property of the category. Once the categories are defined, method elements can be assigned to them and the resulting categories can be used to access the information in the method, as well as in custom categories as part of navigation views. Standard categories cannot be packaged in separate packages in plug-ins, thus alternative categorization schemes must be defined in separate plug-ins. Guidance can also be associated with standard categories. Such guidance should be applicable to the category as a whole, and should not be all guidance that is associated with each of the elements categorized to that category. ### Customizing a Standard Categories It is assumed that the standard category (e.g., domain or discipline) being customized cannot be modified directly. Thus, all changes must be stored in a separate plug-in from the standard category being customized. To see the resulting changes, you need to browse or publish a configuration that includes the original standard category plus the customizations. If you can modify the standard category directly, you should follow the guidelines described in the topic Categorizing Method Elements Using Standard Categories below. There are a number of different ways that you can customize an existing standard category. You can: Assign elements to the category Remove elements from the category Replace an existing standard category with a new standard category Rename the standard category Specific standard category customization scenarios are described in the remaining sections of this guideline. #### Assign elements to the category Perform the following steps to add a method element to an existing standard category: If it does not already exist, create a plug-in to contain the standard category customizations. In the new plug-in, define a standard category that contributes to the existing standard category and assign the new elements. For more information on contribution, see the topic Using Method Content Variability in the Guideline: Defining Method Elements. #### Remove elements from the category Perform the following steps to remove a method element from an existing standard category: If it does not already exist, create a plug-in to contain the standard category customizations. In the new plug-in, define a standard category and assign the same elements as in the original standard category, except for the element you want to remove. Change the definition of the new standard category to extends-replace the original standard category. #### Replace an existing standard category with a new standard category Perform the following steps to replace an existing standard category with a new standard category: If it does not already exist, create a plug-in to contain the standard category customizations. In the new plug-in, define the standard category and assign the desired elements. Change the definition of the new standard category to replace the original standard category. #### Rename an existing standard category Perform the following steps to rename an existing standard category: If it does not already exist, create a plug-in to contain the standard category customizations. In the new plug-in, define a standard category and give it the desired presentation name. Specify that the new standard category is to extend-replace the existing standard category. ### Standard Categories in the UMF The Unified Method Framework (UMF) defines some constraints with regards to the definition and use of standard categories. Those constraints vary for the different standard category types. The UMF implements a Delayed Assignment approach for disciplines, domains and work product kinds. It does not implement a delayed category assignment for role sets because the definition of roles and role sets are strongly linked. Roles are assigned to role sets in the same plug-in as where the roles are defined, the Role Definition plug-in (their definitions are shared). For more information on roles in the UMF, see the topic Roles in the UMF in the Guideline: Defining Method Elements. The UMF also does not implement a delayed category assignment for tools because the assignment of tool mentors to tools does not change (tool mentors are written for a specific tool). For more information on tools in the UMF, see the topic Tool Information in the UMF in the Guideline: Defining Method Elements. The "delayed standard categories" (disciplines, domains and work product kinds) are defined in a Category Definition Base plug-in. Elements are assigned to these categories in the Assign plug-ins associated with the Base plug-in that contains the elements to be assigned (tasks and work products). For information on how these assignments are defined, see the topic Delayed Assignment in the UMF in the Guideline: Defining Method Elements. The benefits to the UMF approach to standard categories are: The same categories can be used with different element assignments (shared Category Definition plug-ins) Alternate category definitions and element assignments can be defined (provide alternate Category Definition and Assign plug-ins) ### Defining Navigation Views This guideline provides recommendations on how to use custom categories to define navigation views. For general information on custom categories, see the topic Categorizing Method Elements Using Custom Categories below. Navigation views are defined as custom categories that define the structure and content of the published method. In general, the following are some criteria that affect how you define navigation views for your method: Number of elements: The more elements you have, the more there is a need to organize them for easy navigation Published representation of the method: How do consumers of the method want to navigate the published method. Define navigation views to support the desired navigation paths. When defining navigation views, it is important to consider the intended audience and usage model of the view, since this will drive the overall organization/hierarchy of the view. For example, will the view be organized by element type or by process area? This information can be captured in the description of the custom category itself. Such information will be helpful to the person who may may want to consider including the navigation view in their configuration for publication. When defining the navigation views, it is a good idea to create a navigation views that represents a natural reading sequence. The guideline to the user would be: "Yes, you CAN click on the links within pages, but that's only if you want to jump to another location in the website, or do some free exploration. If you want to read the material in the recommended order, and make sure you didn't miss anything, then use this navigation view". In such a "natural reading sequence" navigation view, each topic should appear only once. The benefits of this approach are: You can print the configuration You can browse the expanded tree to find a topic (rather than use the "search" feature) You can look for information by logically figuring out what category it logically belongs to. That way even if you don't know the name of a page, you can find it by expanding the appropriate nodes in the navigation view. The following are some navigation views that you my want to consider defining for your method: Welcome view: Includes a Welcome page, as well as About and What's New pages. Provides a starting point for first time users, no matter what their role. Getting Started view: Provides quick access to key concepts, Web site structure and usage information for the new user. Key Elements view: Provides quick access to the key elements of the method -- processes, roles, tasks, work products and processes (it is assumed that guidance is accessible from those elements). Team view: Provides access to all elements in the configuration, organized by method element type and then by category. This views serves as a type of index to all elements in the method. Role-based views: Provides access to the elements of most interest to the role . Process-based views: Provides access to the elements that support the process. Organization/Project-based views: Provides access the the elements of most interest to the organization/project. This view connects the abstractness of the method (content elements and guidance) with the concreteness of project life (physical work products) and encourages the team to live the process. It is minimalist and thus largely artifact-based, but may also include: Links to the current version of artifacts Elements of the development case, Selected guidance Project team information Change Request information Discussion forums ### Navigation views in the UMF The Unified Method Framework (UMF) defines two types of navigation view elements: Configuration-specific, meaning they are intended to be published as part of a specific configuration Common, meaning they are intended to be shared across plug-ins and configurations. The UMF defines navigation view building blocks, which are intended to be used across navigation views, as well as generic navigation views that can be used as-is or in parts in other navigation views. Where the navigation view elements are defined and how elements are assigned to them is different for each. Navigation view building blocks are elements that may be used across a number of navigation views. The UMF navigation view building blocks categorize method elements by "types" as defined in the meta model (i.e., roles, tasks, artifacts, deliverables, outcomes, checklists, guidelines, capability patterns, delivery processes, etc), as well as some other key ones (e.g., release information). The navigation view building blocks are defined as custom categories in Navigation View Definition plug-ins, where they can be shared across plug-ins. If you want to define additional navigation view building blocks, define an Extends plug-in that includes the new building blocks and include the new building blocks in a custom category that contributes to the base navigation view building blocks custom category. Using such "super custom categories" will keep the list of top-level custom categories from getting too long. Generic navigation views are navigation views that may be applicable in multiple configurations. They are also defined as custom categories in Navigation View Definition plug-ins, where they can be shared across plug-ins. Generic navigation views assemble navigation view building blocks into something that can be used as a whole or in parts as a publishable navigation view. For example, a generic navigation view can be used to provide a view of everything in the configuration. These navigation views can be used for specific method configurations as-is, or tweaked to address the specific needs of the configuration (e.g., extend/replace it or ignore and build their own). The benefits of sharing navigation view elements is that you automatically get consistent navigation views. Configuration-specific navigation views are defined as custom categories in the Publish plug-in for the configuration that is to be published. The configuration-specific navigation views indicate what elements elements (or navigation view building blocks) are to be included. When defining a configuration-specific navigation view, you can: Create a new view using existing navigation view elements Reuse the common generic navigation view, replacing and/or adding to selected elements, as needed. Custom categories that are designed to be navigation views should include "view" in the name. Also, the custom categories that represent the navigation view tabs for the configuration should be "packaged" in a parent custom category with "view tabs" in the name. This makes it easy to identify the custom categories that have been designed to serve as the navigation views for the configuration. The UMF also defines a "Do Not Publish" category. It is also defined as a custom category in Navigation View Definition Base plug-ins, where it can be shared across plug-ins. Plug-ins can map specific method elements to this custom category to keep the elements from being published. This category is especially useful for publish plug-ins that are constructing custom views for publishing. The elements in this category should be removed from all publishable configurations. For more information on publishable configurations, see [Concept: Practice Library Configuration Types]. For more information on the UMF plug-in types (e.g., Navigation View Definition plug-ins, Publish plug-ins, etc.), see [Concept: Practice Library Plug-In Types]. ### Navigation Views in the IBM UMF RMC 7.5 (not EPF Composer) has a feature for "tag-based queries" that provides some additional improvements to the common navigation view elements. Using that feature, specific method elements can be tagged with a special key word which is then included as part of a query in a custom category, where the results of the query populate the custom category. The following are some specific ways in which that feature has been leveraged in the UMF content: Release information: "Release information" is not a type, so we can't use the "Include elements of type" feature in the base common navigation view element. So instead, we tag all release information method elements with a "release_info" tag and then replace the placeholder common navigation view element with a custom category that does a tag-based query. [*** I checked and none of the practice release information is tagged. ***] Structured practice list. We tagged all technical practices with a "technical" tag and defined a "technical practice list" custom category that does a tag-based query on "technical". We tagged all management practices with a "management" tag and defined a "management practice list" custom category that does a tag-based query on "management". We then replaced the "structured practice list" placeholder in the common navigation view elements with a custom category that contains the "technical" and "management" tag-based-query custom categories. This way, if you add a new technical practice, you just have to tag the practice element with "technical" and it will appear correctly in the view. [*** I checked and none of the practice release information is tagged. ***] These tag-based-query custom categories are defined in the commercial-level extensions to the base navigation view definition plug-in. These new custom categories are defined to replace the non-query-based custom categories in the base navigation view definition plug-in. ### Categorizing Method Elements Using Custom Categories Custom categories can be used to categorize method elements so that the practitioners can find them easily and quickly. They also form the basis of a published configuration by defining the navigation view structure for the configuration. Custom categories are highly customizable and can contain any type of element. Custom categories allow you to categorize content according to any hierarchical scheme you want and can then be used to compose publishable views, as well as providing a means to organize the method content prior to publishing. For example, you could create a custom category that logically organizes content relevant to your development organization department, such as a Testing category that groups together all roles, work products, tasks, and guidance elements relevant to testing. When defining custom categories, consider the different ways you may want to access the elements, as well as the ways in which the end-user of the method may want to access the method elements. The former may result in ideas for "method management-focused" custom categories, while the latter may result in ideas for navigation view focused custom categories. What information is needed? How does one find that information? Well crafted custom categories will help enormously. Custom categories can be nested to create a categorization hierarchy. For example, if you want to define a navigation view that includes "sub-folders", you can do that by defining a sub-custom category in a navigation view custom category for each folder you would like to be included. Custom categories can also be nested to organize the custom categories. For example, if you define a set of custom categories that are intended to represent navigation views and another set that are not. You may want to package all the navigation view custom categories in a single custom category. In this case, the topmost custom category is more like a package than a custom category. You can add elements to existing categories by defining a custom category that contributes to the original custom category and adds the desired elements. For methods containing a lot of elements and plug-ins, defining a shared set of custom categories can be beneficial for the following reasons: Method authors have a consistent way of categorizing content Method authors and delivery practitioners can find related content more easily and reference it Published configurations will have the same look and feel to the delivery practitioner making the web site easier to navigate and information easier to find Delivery practitioners will require less education and training on the set of configurations with which they work For recommendations on naming custom categories, see the topic Method Element Naming Conventions in the Guideline: General Naming Conventions. Be sure to capture the purpose of the custom category in its description, so that the reason the custom category was created and what it contains is maintained. This will make it easy for other method authors to understand when the category should be used. Custom categories cannot be packaged in separate packages in plug-ins. Thus alternative categorization schemes must be defined in separate plug-ins. ### Customizing a Custom Category It is assumed that the custom category being customized cannot be modified directly. Thus, all changes must be stored in a separate plug-in from the custom category being customized. To see the resulting changes, you need to browse or publish a configuration that includes the original custom category plus the customizations. If you can modify the custom category directly, you should follow the guidelines described above in Categorizing Method Elements Using Custom Categories. There are a number of different ways that you can customize an existing custom category. You can: Add elements to an existing custom category Re-order the elements in an existing custom category Replace an existing custom category Rename an existing custom category Specific custom category view customization scenarios are described in the remaining sections of this guideline. #### Add elements to an existing custom category Perform the following steps to add a method element to an existing custom category: If it does not already exist, create a plug-in to contain the custom category customizations. In the new plug-in, define a custom category that contributes to the existing custom category. For more information on contribution, see the topic Using Method Content Variability in the Guideline: Defining Method Elements. In the contributor, assign the elements you would like to see added to the category. If you want to add a sub-custom category to the category, define a sub-custom category. You can even control the order in which the elements appear in the category, relative to the existing elements. #### Re-order the elements in an existing custom category Perform the following steps to reorder the elements in an existing custom category: If it does not already exist, create a plug-in to contain the custom category customizations. In the new plug-in, define a custom category and assign all the same elements as the original custom category. Re-order the elements in the custom category, as desired. Change the definition of the new custom category to replace the original custom category using method content variability. #### Replace an existing custom category Perform the following steps to replace an existing custom category with a new custom category: If it does not already exist, create a plug-in to contain the custom category customizations. In the new plug-in, define a custom category and assign all desired elements to the custom category. Re-order the elements in the custom category, as desired. Change the definition of the new custom category to replace the original custom category using method content variability. #### Rename an existing custom category Perform the following steps to rename an existing custom category: If it does not already exist, create a plug-in to contain the custom category customizations. In the new plug-in, define a custom category that extends and replaces the existing custom category using method content variability. Give the new custom category the desired presentation name.
This program and the accompanying materials are made available under the Eclipse Public License V1.0, which accompanies this distribution. EPF Copyright.