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.
|