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