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.
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 |
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. Figure 1 provides examples of UMF plug-in names that use these conventions: Figure 1: Example: Method authoring practice naming conventions Notice the following points shown in Figure 1: 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 ("mdev" in this example) All plug-ins that support method authoring are grouped together because a new name level was introduced in the descriptive name ("auth" in this example) 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. For example: practice.mdev.auth.practice_auth.extend_umf and practice.mdev.auth.practice_auth.extend_umf-ibm The licensing level is separated from the rest of the plug-in name with a hyphen. For example: practice.mdev.auth.practice_auth.extend_umf-ibm and practice.mdev.auth.practice_auth.extend_umf-ibm_int. ##### 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 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. The following are some examples of UMF configuration names that use these conventions: Figure 2 provides an example of UMF configuration names that use these conventions. Figure 2: Example: UMF configuration naming conventions Notice the following points shown in Figure 2: 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 ("mdev" in this example) The publish configurations for a specific configurations 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. For example: mdev: Method Development mdev.auth: Method authoring (s sub set of method development) mdev.meth_mgmt: Method Development Method Management Source/licensing level: Same as for plug-ins. Figure 3 provides some examples of UMF configuration project names that use these conventions. Figure 3: Example: UMF configuration project naming conventions ##### 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. Figure 4 provides some examples of UMF tag group names that use these conventions. Figure 4: Example: UMF tag group naming conventions #### IBM Licensing Levels The following are the unique identifiers being used for elements defined at the commercial level and above (they reflect the UMF 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) ### 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.
This program and the accompanying materials are made available under the Eclipse Public License V1.0, which accompanies this distribution. EPF Copyright.