Guideline: General Naming Conventions
This guideline provides recommendations on how to name method elements and writing brief descriptions. It also includes the UMF naming conventions and IBM licensing styles.
Relationships
Main Description

General Naming Conventions

This guidance provides general information on naming method elements.  For method element-specific naming guidance, see the attached guidance.

Abbreviations

It is a good practice is to provide a list of approved abbreviations for your project. Using a standard set of abbreviations simplifies searches for not only the method authoring team, but also for users of your published web site.

Name fields

Most method elements have two name fields:

  • The Name is always present since it is the internal name for the element.
  • The Presentation Name is present for some elements; it is the name displayed in the published web site for the element. Thus, a friendly name should be used.

General naming guidelines

In general, all method elements should following the following recommendations:

  • Name should reflect the essence of the element
  • Where an element has both a name and a Presentation Name field, try to name them consistently (though abbreviations may be used in the internal name)
  • Abbreviations should be either very common to the plug-in domain (for example, J2EE for Java 2 Enterprise Edition) or they should be taken out of a list of common abbreviations for the project. If abbreviations are not standardized, it is very likely that similar but not quite identical abbreviations will occur here and there, introducing confusion and errors later on

For general guidelines on naming variants, see the section on that topic later in this guideline.

Method element-specific naming guidelines

Table 1 provides element-specific guidelines for naming the different types of method elements. 

Table 1: Method Element Naming Conventions

Element Guideline Reason
Plug-in
  • use  internal name for the Name field
  • use friendly name for the Presentation name field
  • Omit the word "plug-in" in the names (it is redundant)

The value of the Name field determines the directory name used in the file system.  

Compound names, separated by periods, can be used in the Name field to organize the list of plug-ins in the library view to make them easier to navigate for process authors. 

Method content package

  • use  internal name for the Name field
  • use friendly name for the Presentation name field

Method content package names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations. Thus, these names need to be easy to understand and self-explanatory.

Process package

  • use friendly name friendly name for Name field (process packages only have a single name field)

Process package names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations. Thus, these names should be easy to understand and self-explanatory.

Standard category
  • use internal name for the Name field
  • use friendly name for the Presentation name field

Standard Category names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations, as well as to include or exclude from other custom categories. Thus, these names should be easy to understand and self-explanatory.

Custom category
  • use internal name for the Name field
  • use friendly name for the Presentation name field

If the custom category is to be used for a navigation view, include "view" in both name fields. 

Custom Category names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations, as well as to include or exclude from other custom categories. Thus, these names should be easy to understand and self-explanatory.

The Presentation name of a custom category that is used as a navigation view is also used as the name of the tab that is published for that view.

Configuration
  • use internal name for the Name field
  • use friendly name for the Presentation name field
  • Omit the word "configuration" in the names (it is redundant)

The Name field determines the file name used in the file system. 

Role
  • use internal name for the Name field
  • use friendly name for the Presentation name field
Task
  • use internal name for the Name field
  • use friendly name for the Presentation name field

Task names should form a verb object phrase. The verb should be carefully chosen to ensure that the action to be performed is clear to the practitioner. For a list of acceptable verbs, see the "Acceptable Verbs" table in a later section.  The object should be closely related to the output work product.

For example:  Define Test Specification
"Define" is the verb and means "to determine the essential qualities". (see Table 2). "Test Specification" is the main output work product for the task.

Alternatively, the task name may reflect the objective of performing the task, instead of being closely related to the output work product.

For example: Plan the Project.

Work product: Artifact
  • use internal name for the Name field
  • use friendly name for the Presentation name field
Work product: Deliverable
  • use internal name for the Name field
  • use friendly name for the Presentation name field
Work product: Outcome
  • use internal name for the Name field
  • use friendly name for the Presentation name field
Guidance
  • use internal name for the Name field
  • use friendly name for the Presentation name field
Capability pattern
  • use internal name for the Name field
  • use friendly name for the Presentation name field

Delivery process
  • use internal name for the Name field
  • use friendly name for the Presentation name field


Acceptable verbs

Table 2 provides a starter set of verbs. Method authors may add verbs but they should do so in such a way that avoids duplication. If a new verb is created, ensure that the definition of what it means is included in the configuration.

Table 2: Acceptable Verbs

Verb Meaning Comments
Acquire To come into possession of  
Analyze To determine the relationship of component parts  
Assemble To fit parts together Especially useful for deliverables
Assess To make a judgment of worth  
Assign To appoint to a post or duty  
Build To construct by putting parts or materials together  
Capture To document  
Categorize To analyze and group according to a particular criteria  
Cleanse To purify  
Communicate To transmit information so that it is understood  
Conduct To direct or manage  
Configure To set up for operation  
Confirm To verify that you have what's needed  
Define To determine the essential qualities  
Detail To provide the details for an outlined artifact  
Develop To bring to maturity;  to provide a more specific definition  
Elicit To draw out or evoke  
Enable To make operational  
Estimate To judge approximate value  
Evaluate To determine significance or worth  
Gather To bring together into one collection  
Gather To locate and bring together  
Identify To establish identity  
Implement To fulfill; to realize  
Initiate To facilitate the beginning  
Install To place in position of use  
Manage To direct or supervise  
Obtain To get or attain by planned action or effort  
Outline To describe key elements  
Perform To do  
Plan To describe objectives, as well as a sequence and deadline for reaching a goal; to specify how to reach a goal
Prepare To make ready  
Prioritize To set priorities  
Receive To acquire, come into possession  
Reconcile To check against another for accuracy and make them match  
Release To make available for use  
Review To examine carefully, looking for errors, omissions, ambiguity, inconsistency    
Run To perform, generally by executing a program on a computer  
Select To choose  
Specify To name or state explicitly or in detail  
Ship To transport an item  
Train To teach a task or job  
Understand To comprehend meaning  
Validate To confirm that a solution or process is correct  
Verify To ensure correctness according to specific criteria  


Do not use leverage because it is marketing jargon and also outdated jargon. We avoid jargon because it always becomes outdated and doesn't translate accurately.

Naming method variants

This section provides specific recommendations on how to name elements that have a variability relationship to another element.

The following table provides guidance about naming specific variants.

Element Guideline Reason
Base element
  • use internal name for the Name field
  • use friendly name for the Presentation Name field 
Contributor
  • use internal name for the Name field
    • use exactly the same name as the element to which the contribution is being made
    • add a suffix that identifies the plug-in providing the contribution
    • if there are multiple contributions to the same element from different packages in the same plug-in, it may also be necessary to identify the content package in the suffix
    • the suffix should be distinct from the name. Use a period (.) to separate a suffix from the name
  • leave Presentation Name field blank (it is inherited)

Do not specify a presentation name for contributing elements because it is inherited from the base element.

The Method Composer tool often provides an indication of the variability type, the content element affected and the plug-in containing the content element affected. It does not do so everywhere, especially in search dialogs. Thus, it is recommended to use the same name as the base as the first part of the name and then include a post-fix to help clarify the plug-in or content package that contains the variant.

To aid in distinguishing between different contributors and the base element, it is a good idea to name contributors differently from the base element.

Replacement
  • use internal name for the Name field
  • use friendly name for the Presentation name field

Note:  If the presentation name of the replacement is identical to the element that it replaces, then follow the naming convention for naming a contributor.

A replacing element replaces the original and results in a new element; therefore, follow the conventions for naming a new element. If you are not changing the presentation name, follow the naming convention for naming a contributor.
Extension
  • use internal name for the Name field
  • use friendly name for the Presentation Name field

An extending element is a new element.  Thus, the name of an extending element should be different from the element being extended.

UMF naming conventions

The Unified Method Framework (UMF) defines a naming convention for each library element: method plug-ins, method configurations, plug-in projects, configuration projects and tag groups.

The UMF naming convention divides the element names into name parts, where each name part is separated by a dot (‘.'). For example, the plug-in name "core.tech.com.base" has four name parts.

The benefits of UMF's naming convention is that it takes advantage of Method Composer support for a hierarchical library view where a new level is introduced for each name part. The resulting hierarchy is defined to optimize configuration of the method. The most important categorization for someone configuring the process is listed first: the plug-in or configuration type.  Licensing level is applied as a suffix and no suffix means open source (in other words, open source method elements do not have a licensing level suffix).

UMF plug-in naming conventions

UMF plug-in naming convention: <plug-in type>.[<context>].<descriptive name>.<plug-in part>[_<part qualifier>][-<source/licensing level>]

Where:

  • Plug-in type:  The following are the possible values for the plug-in type.  For more information on the plug-in types, see [Concept: Practice Library Plug-In Types].
    • core = Core
    • practice = Practice
    • process = Process
    • publish = Publish
    • meth_mgmt = Method Management

  • Context: Not required (some plug-ins are "context-free" meaning that they are not specific to any context).  The following are some examples of contexts: 
    • gen = general purpose (general purpose means applies across multiple contexts.  This is NOT the same as context-free)
    • tech = technology
    • bus = business
    • mgmt = management
    • legacy = legacy
    • mdev = method development 
    • sdpl = solution deployment

Note: If you would like to implement "nested" contexts, you can break the context name into multiple "parts", where each of those parts are separated by a dot (period) so that Method Composer creates a hierarchical view of the related plug-ins. For example: You could define an authoring (auth) context that is a sub-context of method development (mdev). In such a case, the name of the context would be "mdev.auth".   

  • Descriptive name: The following conventions apply to the Descriptive name part of of a plug-in name:
    • Actual names will vary, but the name should be descriptive of what the plug-in contains, should be pretty close to the presentation name for the plug-in, using UMF Approved Acronyms.  
    • For example: Descriptive name: practice_auth; Presentation name: Practice Authoring.
          
  • Plug-in part: The following are the possible values for the plug-in part.  For more information on the plug-in parts, see [Concept: Practice Library Plug-In Types].
    • base = base plug-in
    • assign = assign plug-in
    • extend = extend plug-in
         
  • Part qualifier: Not required. This can be used to provide some additional information about the plug-in part.  This is most applicable for Extend plug-ins, where the part qualifier can be used to indicate the reason for the extension.  For example, UMF-specific extensions to an existing plug-in may be indicated with a "_umf" part qualifier (e.g., "<some plug-in>.extend_umf").   Another example of a qualifier is "gbl" for globalization".
  • Source/licensing level suffix.  Can be used to indicate the company that the plug-in applies to and/or the licensing level of the plug-in. Open source plug-ins do not include a licensing level in their names.
    Note: The use of a hyphen (-) rather than a dot or period (.) is intentional because the source/licensing level is not intended to be another hierarchical level.  Do no use a hyphen in any other place in the name except to separate the actual plug-in name from the suffix.

Note the following:

  • All practices are grouped together because the first part of their names is "practice"
  • All the practices that support a specific context are grouped under the content name
  • All plug-in "parts" for a practice are grouped together because the practice descriptive name is the same
  • The reason for the extension is included as part of the Extend plug-in name, separated from the word "extend" with an underscore and not a hyphen.
  • The licensing level is separated from the rest of the plug-in name with a hyphen.
UMF plug-in project naming conventions

Plug-in projects should be named exactly the same as the plug-ins they contain. See the earlier section on plug-in naming conventions for more information.

UMF configuration naming conventions

UMF configuration naming convention: <configuration type>[.context].<descriptive name>[-<source/licensing level>]

Where:

  • Configuration type: The following are the possible values for the configuration type. For more information on UMF configuration types, see [Concept: Practice Library Configuration Types].
    • publish = Publish Configuration
    • zconstruct = Process Construction Configuration (not commonly used since the advent of configuration-free processes)
  • Context: Same as for plug-ins.
  • Descriptive name: The following conventions apply to the Descriptive name part of of a configuration name:  
    • For Publish configurations, the Practice Configuration name being published makes a good descriptive name
    • For Process Construction configurations, the name of the plug-in that contains the process makes a good descriptive name
  • Source/licensing level: Same as for plug-ins.

Note the following :

  • All configurations of the same type are grouped together because the first part of the configuration name is the configuration type
  • All configurations that support a specific context are grouped under the content name
  • The publish configurations for a specific configuration are easy to spot because the configuration name is in the descriptive name
  • The configuration to be used as the default configuration when constructing a process in a plug-in is easy to spot because the owning plug-in name is in the descriptive name
  • The unique identifier suffix is used to indicate the licensing level of the configurations (e.g., -ibm for commercial content and -ibm_int for internal IBM content)
UMF configuration project naming conventions

UMF configuration project naming convention: configs[-<descriptive name>][-<source/licensing level>]

Where:

Descriptive name: This is optional (i.e., you may only have one tag group per licensing level).  If you use one, the descriptive name should be a name that represents a specific set or category of configurations. 

Source/licensing level: Same as for plug-ins.

UMF tag group naming conventions

UMF tag group naming convention: tags-<descriptive name>[-<source/licensing level>]

Where:

  • Descriptive name: A name that represents a specific set or category of tags.  For example: mdev: Method Development
  • Source/licensing level: Same as for plug-ins.

IBM Licensing Levels

The following are the unique identifiers being used for elements defined at the commercial level and above (they reflect IBM's licensing Levels:

  • ibm = part of IBM's commercial methods (licensing level =  commercial)
  • ibm_int = part of IBM's internal methods (licensing level =  internal)
  • ibm_lic = part of IBM's licensable methods (licensing level = licensable)
  • ibm_prp = part of IBM's licensable methods (licensing level = proprietary) 

Other companies may defined their own licensing levels following similar conventions.

Writing Brief Descriptions

In general, all non-contributing method elements need a brief description. A brief description provides a one or two sentence description of what the element is (in other words, what content the element contains).

Brief descriptions should be written at the time the element is identified. A well-written description is important because if you find it hard to describe what an element is, it may not be a good element

Follow these guidelines when developing method element brief descriptions:

  • Do not include presentation names in brief descriptions because that makes it harder to change the presentation name. Instead, refer to "this <element type>", where <element type> is the type of method element. For example, "this role"... or "this guidance".
  • Do not state the obvious. The brief description should not just repeat what can be understood from the element type and the presentation name. For example, for Concept: Pattern, don't just say, "This concept describes what a Pattern is". Such information does not provide any value. Instead, provide a one or two sentence summary of what the element contains. For example, "This concept describes s generalized solution that can be implemented and applied in a problem situation (a context) and thereby eliminate one or more of the inherent problems."
  • Avoid repeating the brief description in other fields of the method element. If there is nothing more to add to what is in the brief description, then omit the other description fields.
  • Make sure that there is a period at the end of the brief description.
  • Check for general spelling and spacing errors.