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
|
|
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 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
|
|
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
|
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
|
|
|
|
Task
|
|
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
|
|
|
|
Work product: Deliverable
|
|
|
|
Work product: Outcome
|
|
|
|
Guidance
|
|
|
|
Capability pattern
|
|
|
|
Delivery process
|
|
|
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
|
|
|
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 identifty
|
|
|
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 trasnport 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
|
|
|
|
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 diffierent contributors and the base element, it is a good idea to
name contributors differently from the base element.
|
|
Replacement
|
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
|
|
An extending element is a new element. Thus, the name of an extending element should be different
from the element being extended.
|
Special instructions when authoring in the UMF: When naming method elements that are to exist within
the Unified Method Framework (UMF), specific naming conventions must be used. For
more information, see Guideline: UMF Naming Conventions.
|
