Guideline: Implementing a Method Asset |  |
Main Description
### Detailing Method Elements When detailing method elements, be sure to: Use the individual fields of the method element (and associated guidance) instead of putting all the details in the Main description field. This separates and simplifies the detailed text so the reader can easily focus on the information they're interested in. Specifically, use the Brief Description or Purpose sections of method content to state the purpose or conclusion of the idea that's being communicated. Use the remaining sections to provide a detailed explanation of the subject. A method element should immediately communicates the specific idea that's being described. Reading the rest of the sections is useful to understand the detail of the subject. Keep text sparse to allow the reader to quickly scan and locate the information they want. Document process-dependent information separate from the method content element definition. Method content elements should be process independent. Any minor differences/tweaks to the elements based on where they occur in a particular process or lifecycle can be captured in the processes in which the element appears (more on this below). This maximizes the reuse of the method content across processes. Define associations to guidance, not just hyperlinks in the text. If you link to other guidance from the HTML of a guidance element, define an association from the guidance element to the guidance you are referring to. This ensures that Method Composer will help flag those cases where the referenced guidance is not included in the configuration. Adhere to the recommended guidelines for textual content. See Formatting and Writing Tips for Method Authors]. Capture the source of the information being included in the element. This information is important if you ever need to provide source information for the element for documenting ownership rights. Maintain version histories. For more information, see Guideline: Maintaining Change Histories and Version Numbers]. Method elements can be detailed using templates. For more information, see topic Detailing Method Content Using Templates in Guideline: Creating Plug-ins, Practices and Configurations. ### Detailing Common Method Element Fields In general, use the individual method element properties to capture specific information about the element. This simplifies the text so that the reader can easily focus on the information they're interested in. General information: Name Presentation Name Brief Description For information on these topics, see Guideline: General Naming Conventions Detail information: Use the Purpose and Description sections of method element to state the purpose or conclusion of the idea that's being communicated. Use the remaining sections to provide a detailed explanation of the subject. Purpose: Describes the reason for the method element. Main description: Provides an extended description that explains what the method element is beyond what is covered elsewhere. Key considerations: Contains useful material that does not easily fit into any of the other sections, such as advice and guidance of a critical nature. as well as warnings, cautions, pitfalls and dangers Version information: Version: The version number of the element. In many cases, versioning is done at the plug-in level, rather than at the individual element level. Change date: Today's date is entered by clicking in the field. It cannot be removed. Change description: Enter any free-form text. The history of these descriptions is maintained. Authors: Identify the author(s) of this content. Copyright: The element's copyright. This is generally only completed for the plug-in, since every element gets the plug-in's copyright, unless it is overridden for a particular element. Icon: Shape icon: Specify the icon to be displayed in the upper left of the content page when published. Define a new icon or use one from another plug-in. Node icon: Specify the icon displayed by this node in the tree view of the published site. Define a new icon or use one from another plug-in. ### Detailing Practice Elements Detailing a Practice is all about fleshing out the details of the individual practice elements. All practice detailing work must adhere to the constraints defined for the Practice Framework and for the practice itself. When detailing any element that physically resides in a practice, do not refer to elements outside of the practice. Exception: practice elements may refer to Work Product Slots and other core elements. In addition to the method elements included in a practice (for example, tasks, guidance, and so on), every practice should include the following guidance elements: how-to-adopt roadmap: describes how to adopt the practice practice guidance element #### Detailing practice elements in the UMF When detailing the elements in a practice that exists within the Unified Method Framework (UMF), you must take into consider the UMF practice conventions. When detailing the elements in a practice, you may find that you need to make changes to an element in a Core plug-in. Specifically, you may find that you have content that would be better shared between practices (for example, a common work product, some shared guidance, or a new role) and thus you may need to add a new or refine an existing core element. Alternatively, you may find that if you were to refine an existing Core element that would be able to use it. ### Detailing Work Products This topic provides guidance for detailing work products (artifacts, outcomes and deliverables). Purpose: The Purpose field describes the reason for the method element. For example, for a Work Product: Why is the work product produced? How will it be used? Do not repeat text already stated in other fields, such as the brief description or the main description. Main description. This field is optional for work products. It contains a detailed description of the work product if the Brief description and Purpose is insufficient. If the work product has significant state, include a state machine (i.e., a description of the states and their transitions) in the artifact's Main description. Key Considerations: This field is optional. It contains useful material that does not easily fit into any of the other sections, such as advice and guidance of a critical nature, as well as warnings, cautions, pitfalls and dangers. Impact of not having: List and briefly describe the consequences of not producing this work product. Consider this from the delivery practitioners' point of view. If the work product was not available, what would be the impact to the execution of the project? What information would the practitioners not have that they need? Write a short description of the impact. Reason for not needing: List the conditions when the work product might not be needed, and why. Is the information available somewhere else? Is it of secondary importance to other work products? Is the project small enough that it is not relevant? Write a short description of the normal reasons why the work product may not be needed. Guidance: Guidance can be associated to a task to provide further details about the work product. The type of guidance that is usually associated with a work product includes checklists, examples and templates. For work-product-type-specific guidelines, see the following sections. #### Detailing artifacts The following fields are artifact-specific: Brief outline: This field is optional. It describes the major sections or information topics that are covered by the work product. This information should be generic, in other words, not specific to any particular format or template. Selected representation: This field is optional. It is used when a particular representation is decided on. For example, a particular company may mandate the use of a particular tool or format. Notation: This field is optional. It describes any notations used by the work product. Either Brief outline or Notation should be provided, or both [*** I got this last sentence from the template, but I am not sure what it means. Should it be "not both"? ***] This field may also contain explanations of any diagrammatic or textual notations. Include notations that are important or special terms, labels, headers, acronyms, etc. that are used in the artifact. Any items relating to how this is implemented in a specific template should be included in the description for that template, not here. Note this section should be general enough to apply regardless of the actual representation option selected, unless there are multiple notations such as IDEF1X or UML, in which case an overview of each can be included (preferably as contributions from the related techniques). Representation options: This field is optional. Describe alternative representations for this work product. #### Detailing deliverables The following fields are deliverable-specific: External Description: This field is intended to be a description of the deliverable that the client will read. It is usually copied into a Statement of Work or other agreement, or into sales and marketing material with a client. The content of this field may require legal approval of some sort. Seek guidance from the method authoring consultant. Keep to a description (what the deliverable is) rather than its use in an engagement. Build on the purpose but differentiate between the what and the why of the deliverable. The description is about what the deliverable is. The description must be understood by potential clients. Packaging Guidance: This field is intended to give an overview of the notation for the deliverable. For a root deliverable from which other will be derived, the packaging guidance should indicate the preferred notations. Note the plural here in that there may be several notations. The packaging guidance should provide a synopsis of them. For derived deliverables, variability can add details to notation and they can become more focused. The packaging guidance must account for the availability (or not) of a complete set of input work products. Depending on the configuration tailoring on a particular engagement, all input work product may not be available. Be aware of the purpose and governance level of the deliverable being defined when outlining notation. [*** Describing how the inputs are assembled into a deliverable including what particular sections may be relevant and what the expected state of those inputs should be along. Explicit guidelines on the formatting may be better included via a customization for that project of standard guidelines for a project that applies to all deliverables as defined in the agreement. ***] Deliverable Parts: Identify the work products that will be used to construct the deliverable. ### Detailing Tasks In general, when detailing a tasks (and task steps), provide specific instructions (i.e., prescriptive text). Most text should focus on what needs to be done to accomplish the task (or an individual step of the task). Avoid long descriptions of motivations, reasons, and philosophy. Avoid descriptions that sell the importance of what needs to be done or motivates the steps that need to be performed. Motivations and explanations are placed in guidance such as concepts and supporting materials. Use guidance such as guidelines to provide detailed descriptions of how to perform steps, or to provide steps for alternative circumstances. These motivations can be referenced or linked from the prescriptive text. Purpose: The Purpose field describes the reason for the method element. For example, for a task: Why is the task being performed? When a task is defined to get a work product to a particular state, identifying the purpose of the work product state may help to clarify why the task has been broken down as it has. What is the goal of the task? Main description: This field is optional for tasks if individual steps are being used. If individual steps are not being used, the Main description should explain the execution of the task and mention the input and output work products. Do not repeat text already stated in other fields, such as the Brief description or the Purpose. The task details can be described using the Main description or by including specific Steps. Guidance can be attached to provide further details about how to perform the task. Key Considerations: This field is optional for tasks. It contains useful material that does not easily fit into any of the other sections, such as advice and guidance of a critical nature, as well as warnings, cautions, pitfalls and dangers. Alternatives: This field describes different ways to accomplish the task that could be chosen. This field is not really used any more. It is recommended that you leave it blank. Steps: Steps can be specified to provide a more detailed set of instructions for the practitioner on to how to complete the task. Tasks can be defined by providing: A Main description and no Steps Steps and no Main description A summary or overview of the steps in the Main description, along with specific Steps. A Step is described using: Name: This is the brief description of the step. Description: This optional field provides more detail for the specific step. Guidance: Guidance can be associated to a task to provide further details about how to perform the task or a specific task step. ### Writing Tasks Provide specific instructions – prescriptive text – to perform tasks, activities, and road maps. Most text should focus on what needs to be done to accomplish the step. Avoid long descriptions of motivations, reasons, and philosophy. Focusing on "what to do" in tasks, activities, and road maps. Avoid descriptions that sell the importance of what needs to be done or motivates the steps that need to be performed. Motivations and explanations are placed in guidances such as concepts and supporting materials. Use guidances such as guidelines to provide detailed descriptions of how to perform steps, or to provide steps for alternative circumstances. These motivations can be referenced or linked from the prescriptive text. When writing steps for tasks, activities, and road maps focus on: The steps that need to be performed The conditions or states that need to be achieved Environmental issues that may need to be overcome This information could also be maintained and referenced in a separate plug-in. For example, a Globally Distributed Team plug-in could be created that contains the required guidance. Tasks could be extended through the contribution mechanism to reference the guidelines in the plug-in. #### Prescriptive text examples This is an example of a single step in a task. At first glance it appears prescriptive: Step: Determine Architectural Impact For each change request, the Architect examines the product architecture and determines if an architectural change needs to be made. The architecture must be clearly defined to perform this step. Usually, the architecture has been defined and implemented in the Elaboration iteration of a previous development cycle. If a Software Architecture Document doesn't exist it may be necessary to reverse- engineer the architecture so this task can be performed. The time taken to reverse-engineer the architecture can be attributed to perfective maintenance. Acquiring a clear description of the architecture extends the maintainable life of a software system. Look for behavioral and structural changes such as: Architecturally significant flows that must be changed. Critical interfaces that must be re-implemented. New interfaces that must be created that will be utilized by a significant percentage of the system. Important data transformations that are added, removed, or need to be moved to another part of the system. New generalization dependencies that may be required. Generalization dependences that will disappear, for example a parent-child relationship that will be removed when a new pattern is applied. Operation signature changes that occur on heavily used interfaces. Upgrades to non-functional aspects of the system (performance, security, usability, etc) System interface changes that cause other system components to change #### Analysis "For each change request, the Architect examines the product architecture and determines if an architectural change needs to be made." What the architect really does is "determine if an architectural change needs to be made". The text "examines the product architecture" is vague and doesn't really add much for a seasoned practitioner. If there is a technique to be applied, it belongs in a guideline. "The architecture must be clearly defined to perform this step." This doesn't help the seasoned practitioner. It doesn't say why the architecture wouldn't be clearly defined (presumably in the final process an architecture has been defined), or what to do if the architecture is not clearly defined. If there is some guidance on how to deal with architectural issues when no architectural description exists, then that should be provided in a guideline. "Usually, the architecture has been defined and implemented in the Elaboration iteration of a previous development cycle." This presumably has been done, so stating it in this step is redundant and reduces the clarity of what the step. It also assumes a particular lifecycle is being used in the practice. Practices should avoid assuming a particular lifecycle is being used so the practice is reusable. "If a Software Architecture Document doesn't exist it may be necessary to reverse-engineer the architecture so this task can be performed." This is another pre-requisite. It's also something that only needs to be done once so it shouldn't be part of a step that is repeated like this one (once for each change request). It should probably be placed in a task that's performed at the beginning of the Elaboration phase. "The time taken to reverse-engineer the architecture can be attributed to perfective maintenance. Acquiring a clear description of the architecture extends the maintainable life of a software system." This is useful motivation but it's not prescriptive so it doesn't belong in the task step. It should be in a concept referenced from a step that indicates when reverse-engineering should be performed. "Look for behavioral and structural changes such as..." These bullet points are not about the goal of the step, and so are good candidates for moving to a guideline. #### Here's the improved step: Step: Determine Architectural Impact The Architect reviews each change request and determines if an architectural change is required to implement it. See the guideline "Determining Architectural Impact" for information on how to identify changes that may have a significant impact on the architecture. Using the purpose, description, steps, and guidelines sections of method elements separates and simplifies text so the reader can easily focus on the information they're interested in. Keep text sparse to allow the reader to quickly scan and locate the information they want. ### Detailing Guidance Main Description: This field is the key field of all guidance elements. Care should be taken to distinguish between guidance that may be embedded and that which should be referenced. When third party material is used, the method author must ensure that permission exists for its use in the intended context. For guidance-type-specific guidelines, see the following sections. #### Detailing checklists The Main description field is optional in a checklist as the key content of a checklist are the check items. The following fields are specific to checklists: Check Items: These fields make up the items in the checklist. Each check item has: Name: This is the short description of the check item. These should be written as verifiable statements rather than questions, items for consideration, or guidance. If the check item does not always apply the conditions for when to use that check item should be appended to the name in curly brackets { }. Description: This field is optional. It provides additional detail for the check item. If these are "sub-check items" they should also be written as statements. Note: It is usually not necessary to have a main description for a checklist if the required content is covered by the associated check items, conversely it may be feasible to have a checklist with no check items if the text of the main description adequately covers what is to be reviewed #### Detailing examples When detailing an example: Make sure the Brief description summarizes the example, and summarize the context in which it was used. The more specific the better. For example: "This is an example of a requirements management plan for a safety-critical application." (optionally) Attach an actual example to the guidance. (optionally) In the Main description, you can describe what the example represents and how it guides the user in working with the real work product. #### Detailing guidelines When entering text in the Main description if guideline elements, exceptionally lengthy guidance should either be broken down into multiple guidance elements, or attached as a word document. Note that word documents are difficult to translate, and so should be avoided in commercial content. #### Detailing reusable assets When detailing a reusable asset: Make sure the Brief description summarizes the reusable asset, the problem it solves and the context in which it is applicable. The more specific the better. Attach an actual reusable asset to the guidance In the Main description, describe how to apply the reusable asset #### Detailing templates When detailing a template: Make sure the Brief description summarizes the context, format, and tool applicable for this template. For example "This is an informal Word document template." If format such as "letter" versus "A4" is important, that can also be stated. Attach actual template files to the guidance (optionally) In the Main description, provide information about the structure of template and how to use it. You may want to include a description of how to fill out each section of the template. #### Detailing tool mentors When detailing a tool mentor, explain how to apply a specific tool to accomplish a task, performs a set of steps or instantiates a particular work product. #### Detailing white papers When detailing a white paper: Make sure the Brief description summarizes the white paper. The more specific the better. If it is short, you can include the white paper's abstract Attach white paper to the guidance (optionally) In the Main description, you can provide more details on the white paper. If the abstract is long, it can also be included in the Main description. #### Detailing practice authoring guidance Every practice includes the following standard guidance elements: How-to-Adopt roadmap: describes how to adopt the practice practice guidance element The following sections provide recommendations on what to include in these elements when detailing the practice. ##### Detailing the how-to-adopt roadmap Capture the following in the Main description field: Getting Started section: Include information on how to get started using the techniques described in the practice Common Pitfalls section: Describe some common pitfalls when adopting the practice ##### Detailing the practice guidance element Provide the following content in each of the element fields: Brief description: Include one or two sentences describing what this practice covers. Purpose: Include content that describes the business value of this practice -- what do you get when you adopt it? This section is essentially the value proposition for the practice. You may want to describe some common problems and how this practice solves those problems. Main description: This field is optional. It can be used to elaborate on the practice. However, it should be kept brief because this is the first page that users are exposed to, and it is better if that page is short so as not to overwhelm them. How to read this practice: This field is optional. It can include content on the best way to read this practice: For example: "The best way to read this practice is to first familiarize yourself with its overall structure -- what it is in it and how it is organized. The best place to start is with the Key Concepts for the practice -- those concepts that are critical to understand in order to adopt the practice. Once you understand the key concepts, you can turn your attention to the Work Products produced by the practice. Then you can review the practices Tasks. From the work products and the tasks, you can access applicable guidance -- guidelines and tool mentors associated with each task provide details of how to perform the task. Templates and checklists associated with the work products guide you in their completion and evaluation. You can also access the guidance provided by the practice directly, via the Guidance folder. Levels of adoption: This field is optional. It can be used to provide information about levels of adoption of this practice. For example, you may initially adopt a practice by using a few of the recommended work products and over time use the remaining ones. Additional information: Use this field to provide enablement information for this practice. For example: available books, articles, training courses, and so on. References: These are the associations to all the elements that are considered part of the practice. ### Detailing Roles Key Considerations: This field contains useful material that does not easily fit into any of the other sections, such as advice and guidance of a critical nature. as well as warnings, cautions, pitfalls and dangers. Skills: This field identifies specific skills needed to fulfill this role. List the skills for the role in bullet form. Ensure that each bullet addresses a separate skill. Assignment approaches: Enter any assignment considerations of which the delivery practitioners should be aware. For example, this field might be used to provide advice to the project manager running an engagement. Synonyms: This field identifies alternate names for the role. Identify different terminology an organization may have. Role names more familiar to the users of the process may be identified here. This clarifies vocabulary and helps users of the published process clarify and transition to terminology provided in base content. ### Writing Tool Mentors Write tool mentors with a specific goal or intent in mind. Often the best way to do this is to tightly link the tool mentor with task steps or a guideline. Tasks describe what need to be done, and guidelines describe how to do something. Both types of elements are goal oriented and can gain value from tool support. Tool mentors take the perspective that the reader should use a tool to achieve a specific objective that provides some value. This is much like the intent of a use case. Take advantage of this similarity by leveraging use case techniques to create a tool mentor. For example: Identify the tool mentor and stakeholder. Focus on what the stakeholder's objectives are. Use this information to create the brief description. Outline the tool mentor. Follow the task steps or the timeline in a guideline to help order the outline. The reader should understand what they need to do with the tool at each step. Make sure the reader achieves their objective by the time they reach the last step of the tool mentor. Handle problems and issues that could arise. Assure the reader understands what to do if they get unexpected results. Detail the tool mentor. Include references to help text whenever appropriate. It's common to reference specific information in the product help text at almost every step of the tool mentor. Review the tool mentor and assure that it's clear how to achieve the reader's objective. The transition between the task or guideline and the tool mentor should be clean. The reader shouldn't see anything unusual or surprising when moving from the task/guideline to the tool mentor. Always use a Tool Mentor guidance type to write a tool mentor. Don't add tool information directly to tasks, guidelines, work products, etc. This keeps tooling information separate from the process content (see below). #### Tool mentors and help text Don't use tool mentors as Help Text. Help Text is shipped as part of the associated product and describes what features do and how to use them. Tool mentors focus on achieving a goal, while Help Text describes how to use specific features and functions of a product. Reference the help as often as necessary in the tool mentor, but don't supplement or duplicate the help text. #### Organizing tool mentor content in the library (RMC) Categorize the tool mentors properly in the plug-ins using Standard Categories. See Guideline: Categorizing Method Elements Using Standard Categories. See Guideline: Tool Information in the UMF for information on placing the tool mentor content in plug-ins to conform with UMF. Method content is usually written to be tool agnostic. Tool mentors provide tool-specific information and are structured so they they can be easily removed from a published configuration. This has two benefits: Users can perform steps manually or add their own tooling information if they don't own IBM tools. We can manage tool information independently of content so it's easier to address new features, add new tools, and remove tools that have been end-of-lifed. ### Detailing Processes The following fields are present for all processes: Purpose (optional): Describe the ultimate objective of the process. May not be needed if such information has been included in the Brief description. Main description: This is where you describe the flow of the process textually, referencing the activities in the process, as needed. Scope (optional): Describe what is included as part of the process and/or what is not. Usage Notes (optional): This is especially important for capability patterns that are intended to be used in other processes. This is where you describe how the capability pattern might be used. Alternatives (optional): Describe different ways in which this process could be performed. How to Staff (optional): Describe the skills you might need to execute this process. Key Considerations (optional): Describe things you might want to take into consideration when performing this process. The following fields are specific to delivery processes: Scale (optional): The size of projects this process is intended for (e/g/. large, small, etc.) Project Characteristics: Describe the types of projects the process was intended for Risk Level (optional): The level of risk associated with this process. Estimating Techniques: Not used. This is really something that should be tracked in a project management tool Project Member Expertise (optional): Describe the skills you might need to execute this process. Type of Contract (optional): Describe the type of contract (e.g., fixed price, time and materials, etc.) that this process would be most appropriate for.
This program and the accompanying materials are made available under the Eclipse Public License V1.0, which accompanies this distribution. EPF Copyright.