| <?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.5/uma.ecore" |
| xmlns:epf="http://www.eclipse.org/epf" epf:version="1.5.0" xmlns:rmc="http://www.ibm.com/rmc" |
| rmc:version="7.5.0" xmi:id="-oU9Eo7WO9ooJKChDS3FhlA" |
| name="detailing_guidance,_60WTkJkoEd2Al9G_gP7uDg" guid="-oU9Eo7WO9ooJKChDS3FhlA" |
| changeDate="2008-10-13T06:05:13.890-0700" version="1.0.0"> |
| <mainDescription><p>
 |
| This guideline provides guidelines for detailing <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/guidance_549AC394.html"
 |
| guid="_83ttAB_NEdq6CKKKq4D7YA">guidance</a>.&nbsp;For general detailing guidelines that are common to all method
 |
| elements, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/detailing_method_elements_general_B2500E20.html"
 |
| guid="_jLqqIOFIEdumFeaOJSgmnQ">Guideline: Detailing Method Elements (General)</a>.
 |
| </p>
 |
| <p dir="ltr">
 |
| Keep in mind the following guidelines when completing each of the&nbsp;guidance-specific text fields (for guidelines
 |
| regarding the common fields, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/detailing_common_method_element_fields_940D3CE0.html"
 |
| guid="_zVLrkJZwEd2ireJkqESkdQ">Guideline: Detailing Common Method Element Fields</a>):&nbsp;&nbsp;&nbsp;
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Main Description: This field is the key field of all guidance elements.&nbsp;<br />
 |
| Care should be taken to distinguish between guidance that may be embedded and that which should be
 |
| referenced.&nbsp;When third party material is used, the method author must ensure that permission exists for its
 |
| use in the intended context.&nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| </ul>
 |
| <p dir="ltr">
 |
| For guidance-type-specific guidelines, see the following sections.&nbsp;&nbsp;&nbsp;
 |
| </p>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing checklists
 |
| </h3>
 |
| <p>
 |
| The Main description field is optional in a <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/checklist_D780FDF.html"
 |
| guid="_7vpJsMaCEduMlb2cQZNTYw">checklist</a>&nbsp;as the key content of a checklist are the check items.
 |
| </p>
 |
| <p>
 |
| The following fields are specific to checklists:
 |
| </p>
 |
| <blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| <strong>Check Items:</strong>&nbsp; These fields make up the items in the checklist.&nbsp; Each check item has:
 |
| </p>
 |
| <ul dir="ltr">
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| <strong>Name:</strong>&nbsp; This is the short description of the check item. These should be written as
 |
| verifiable statements rather than questions, items for consideration, or guidance.&nbsp;If the check item
 |
| does not always apply the conditions for when to use that&nbsp;check item should be appended to the name
 |
| in&nbsp;curly brackets { }.&nbsp; &nbsp;
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| <strong>Description:</strong>&nbsp; This field is optional. It provides additional detail for the check
 |
| item.&nbsp;If these are&nbsp;"sub-check items" they should also be written as statements.&nbsp;
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| <p style="MARGIN-RIGHT: 0px">
 |
| <em>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</em>&nbsp;&nbsp;&nbsp;
 |
| </p>
 |
| </blockquote>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing examples
 |
| </h3>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When detailing an <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/example_9C7688B0.html"
 |
| guid="_nE6fsMaFEduMlb2cQZNTYw">example</a>:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| Make sure the Brief description summarizes&nbsp;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."
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| (optionally) Attach&nbsp;an actual example to the guidance.
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| (optionally) In the Main description, you can describe what the example represents and how it guides the
 |
| user&nbsp;in working with the real work product.
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing guidelines
 |
| </h3>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When entering text in the Main description if <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/guideline_1D590B95.html"
 |
| guid="_uK8HMMaFEduMlb2cQZNTYw">guideline</a>&nbsp;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.
 |
| </p>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing reusable assets
 |
| </h3>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When detailing a <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/reusable_asset_C02B1B80.html"
 |
| guid="_kSKZUMaHEduMlb2cQZNTYw">reusable asset</a>:
 |
| </p>
 |
| <ul dir="ltr">
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| Make sure the Brief description summarizes&nbsp;the reusable asset, the problem it solves and the context in
 |
| which it is applicable.&nbsp;The more specific the better.
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| Attach&nbsp;an actual reusable asset to the guidance
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| In the Main description, describe how to apply the reusable asset
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing templates
 |
| </h3>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When detailing a <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/template_53432085.html"
 |
| guid="_1MLN8MaIEduMlb2cQZNTYw">template</a>:
 |
| </p>
 |
| <ul dir="ltr">
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| 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.
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| Attach&nbsp;actual template files to the guidance
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| (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.
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing tool mentors
 |
| </h3>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When detailing a <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/tool_mentor_264766F3.html"
 |
| guid="_yYy-mdnmEdmO6L4XMImrsA">tool mentor</a>, explain how to apply a specific tool to accomplish a task, performs a
 |
| set of steps or instantiates a particular work product.&nbsp;
 |
| </p>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Detailing white papers
 |
| </h3>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When detailing a <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/white_paper_7231747.html"
 |
| guid="_Kc1IIMaJEduMlb2cQZNTYw">white paper</a>:
 |
| </p>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| <ul>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| Make sure the Brief description summarizes&nbsp;the white paper. The more specific the better. If it is
 |
| short, you can include the white paper's abstract
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| Attach&nbsp;white paper to the guidance
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div style="MARGIN-RIGHT: 0px">
 |
| (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.
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| </div></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |
