<?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="-sS_V1mBuq6l6GFWtfOF6iw"
    name="new_guideline,_WLs-UKnUEd2eRp4Z7dEEOQ" guid="-sS_V1mBuq6l6GFWtfOF6iw" changeDate="2008-11-13T09:37:37.875-0800"
    version="7.5.0">
  <mainDescription>&lt;p>&#xD;
    Documenting the architecture of a &lt;a class=&quot;elementLink&quot;&#xD;
    href=&quot;./../../../core.mdev.common.base/guidances/concepts/practice_fw_6DA4D54D.html&quot;&#xD;
    guid=&quot;__LjaEFQsEd2uvIuuFjd1Fg&quot;>Practice Framework&lt;/a>&amp;nbsp;is critical to making sure that key decisions are captured&#xD;
    and communicated to the development team. Documenting the practice framework architecture involves defining and&#xD;
    capturing the key guiding principles and a consistent approaches for structuring the framework, as well as documenting&#xD;
    the key structural elements.&amp;nbsp;&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    In general, don't spend much time:&#xD;
&lt;/p>&#xD;
&lt;ul>&#xD;
    &lt;li>&#xD;
        getting the architecture perfect -- it can evolve over time as the individual method elements are defined and&#xD;
        detailed.&amp;nbsp;&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        providing detailed descriptions of the method elements -- just name and briefly describe the elements and enter a&#xD;
        few outline details if it helps to more clearly describe the element's basic definition.&#xD;
    &lt;/li>&#xD;
&lt;/ul>&#xD;
&lt;p>&#xD;
    Note: While documenting the architecture is important, it is not enough to just define&amp;nbsp;it on paper.&amp;nbsp;It is&#xD;
    important that the architecturally-significant method elements be actually built using your selected method&#xD;
    implementation environment.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    When documenting the architecture, there are two key decisions that you need to make: what to include in the&#xD;
    architecture description and what level of detail. Each of these are described in the following sections.&#xD;
&lt;/p>&#xD;
&lt;h3>&#xD;
    Architecture content&#xD;
&lt;/h3>&#xD;
&lt;p>&#xD;
    The &lt;strong>&lt;em>architecturally-significant method elements&lt;/em>&lt;/strong> in a practice framework&amp;nbsp;are the&#xD;
    following:&#xD;
&lt;/p>&#xD;
&lt;ul>&#xD;
    &lt;li>&#xD;
        &lt;a class=&quot;elementLink&quot; href=&quot;./../../../core.default.uma_concept.base/guidances/concepts/practice_F5C8EAAB.html&quot;&#xD;
        guid=&quot;_qhCTAFRREd2CWscN8Mx6rg&quot;>Practice&lt;/a>s&lt;br />&#xD;
        &amp;nbsp;&amp;nbsp;&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Core elements: Elements shared across practices:&#xD;
    &lt;/li>&#xD;
    &lt;li style=&quot;LIST-STYLE-TYPE: none&quot;>&#xD;
        &lt;ul>&#xD;
            &lt;li>&#xD;
                &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.mdev.common.base/guidances/concepts/work_product_slot_D5B44CE7.html&quot;&#xD;
                guid=&quot;_Er1OcJIfEdybeduord13cg&quot;>Work Product Slot&lt;/a>s: Information that passes between the practices&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Common method content elements (especially, &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/role_37A0C602.html&quot;&#xD;
                guid=&quot;_yUefQNnmEdmO6L4XMImrsA&quot;>role&lt;/a>s, &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/guidance_549AC394.html&quot;&#xD;
                guid=&quot;_83ttAB_NEdq6CKKKq4D7YA&quot;>guidance&lt;/a>, &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): Definitions that are shared across practices&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Common&amp;nbsp;standard categories (especially &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/domain_D8238B93.html&quot;&#xD;
                guid=&quot;_yHEVYdnmEdmO6L4XMImrsA&quot;>domain&lt;/a>s, &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/discipline_7667F451.html&quot;&#xD;
                guid=&quot;_yGUuidnmEdmO6L4XMImrsA&quot;>discipline&lt;/a>s, &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_kind_F04A382B.html&quot;&#xD;
                guid=&quot;_QWhfYMaJEduMlb2cQZNTYw&quot;>work product kind&lt;/a>s, &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/role_set_396DC9DB.html&quot;&#xD;
                guid=&quot;_Fs8HAMaIEduMlb2cQZNTYw&quot;>role set&lt;/a>s, &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/tool_D0FBC781.html&quot;&#xD;
                guid=&quot;_BangwMaJEduMlb2cQZNTYw&quot;>tool&lt;/a>s)&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Common &lt;a class=&quot;elementLinkWithUserText&quot;&#xD;
                href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/custom_category_554AC4D6.html&quot;&#xD;
                guid=&quot;_eqw94MaFEduMlb2cQZNTYw&quot;>custom categories&lt;/a>&lt;br />&#xD;
                &amp;nbsp;&#xD;
            &lt;/li>&#xD;
        &lt;/ul>&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        &lt;a class=&quot;elementLink&quot; href=&quot;./../../../core.mdev.common.base/guidances/concepts/practice_config_CC7754F2.html&quot;&#xD;
        guid=&quot;_0H9aAO7EEdy9EOwDlaw7Kw&quot;>Practice Configuration&lt;/a>s:&amp;nbsp;Assemble practices into usable methods for&#xD;
        practitioners&#xD;
    &lt;/li>&#xD;
&lt;/ul>&#xD;
&lt;p>&#xD;
    The following are some examples of the &lt;strong>&lt;em>types of decisions&lt;/em>&lt;/strong> you might make (and document) when&#xD;
    architecting a method framework:&#xD;
&lt;/p>&#xD;
&lt;ul>&#xD;
    &lt;li>&#xD;
        Use a &lt;a class=&quot;elementLink&quot;&#xD;
        href=&quot;./../../../core.mdev.common.base/guidances/concepts/delayed_assignment_24142865.html&quot;&#xD;
        guid=&quot;_rlrykJcbEd2sTqxclDgvog&quot;>Delayed Assignment&lt;/a>&amp;nbsp;approach for &lt;a class=&quot;elementLink&quot;&#xD;
        href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/role_37A0C602.html&quot;&#xD;
        guid=&quot;_yUefQNnmEdmO6L4XMImrsA&quot;>role&lt;/a>&amp;nbsp;assignments and standard category assignments (except for &lt;a&#xD;
        class=&quot;elementLink&quot; href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/tool_D0FBC781.html&quot;&#xD;
        guid=&quot;_BangwMaJEduMlb2cQZNTYw&quot;>tool&lt;/a>s) in order to improve the flexibility and configurability of the framework&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Use a specific set of &lt;a class=&quot;elementLink&quot;&#xD;
        href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/method_plugin_190B9F5E.html&quot;&#xD;
        guid=&quot;_D4TLgMaGEduMlb2cQZNTYw&quot;>method plug-in&lt;/a>&amp;nbsp;and &lt;a class=&quot;elementLink&quot;&#xD;
        href=&quot;./../../../core.default.uma_concept.base/guidances/termdefinitions/method_configuration_C2B8FA8A.html&quot;&#xD;
        guid=&quot;__V7pAMaEEduMlb2cQZNTYw&quot;>method configuration&lt;/a>&amp;nbsp;types in order to provide a consistent approach for&#xD;
        structuring the framework. We recommend the plug-in types defined in &lt;a class=&quot;elementLinkWithType&quot;&#xD;
        href=&quot;./../../../core.mdev.common.base/guidances/concepts/practice_lib_plugin_types_3EA8002F.html&quot;&#xD;
        guid=&quot;__428YO6cEdygKbJMUVNEtg&quot;>Concept: Practice Library Plug-In Types&lt;/a>&amp;nbsp;and the configuration types defined&#xD;
        in &lt;a class=&quot;elementLinkWithType&quot;&#xD;
        href=&quot;./../../../core.mdev.common.base/guidances/concepts/practice_lib_config_types_B96A959A.html&quot;&#xD;
        guid=&quot;_1gchoO6dEdygKbJMUVNEtg&quot;>Concept: Practice Library Configuration Types&lt;/a>.&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Follow a consistent set of naming conventions. We recommend the ones&amp;nbsp;defined in &lt;a class=&quot;elementLinkWithType&quot;&#xD;
        href=&quot;./../../../core.mdev.common.base/guidances/guidelines/method_element_naming_conventions_4A4F743B.html&quot;&#xD;
        guid=&quot;_lAphAF5-EduT-Px7fh0LSg&quot;>Guideline: Method Element Naming Conventions&lt;/a>.&amp;nbsp;&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Provide recommendations and constraints for the following:&#xD;
    &lt;/li>&#xD;
    &lt;li style=&quot;LIST-STYLE-TYPE: none&quot;>&#xD;
        &lt;ul>&#xD;
            &lt;li>&#xD;
                How &lt;a class=&quot;elementLink&quot;&#xD;
                href=&quot;./../../../core.mdev.common.base/guidances/termdefinitions/navigation_view_8F89044.html&quot;&#xD;
                guid=&quot;_X_hFIPAjEdyHz_B1XFOUgA&quot;>navigation view&lt;/a>&amp;nbsp;should be built&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                How standard categorization should be handled (as well as any common standard categories)&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Approach for assigning roles&amp;nbsp;(as well as any common roles)&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Approach for scaling elements&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Approach for associating guidance&#xD;
            &lt;/li>&#xD;
            &lt;li>&#xD;
                Approach for dividing the architecture into smaller chunks to reduce complexity&#xD;
            &lt;/li>&#xD;
        &lt;/ul>&#xD;
    &lt;/li>&#xD;
&lt;/ul>&#xD;
&lt;h3>&#xD;
    Level of detail&#xD;
&lt;/h3>&#xD;
&lt;p>&#xD;
    There is a range of&amp;nbsp;options for the information that can be captured in an architecture description. In some&#xD;
    cases, where there is an architectural decision to be made, there are a set of architecture notes that are written up&#xD;
    proposing what to do, discussing all the choices and the tradeoffs that have been made. These notes can be an email&#xD;
    thread, a forum thread, or a wiki. Then, the final decision is captured in an architecture document. The notes serve as&#xD;
    a historical record of decisions (if you keep them) and not a polished, maintained view of the architecture. The&#xD;
    maintained architecture document is a separate work product that is mainly targeted at new developers and maintainers&#xD;
    of the system, and to ensure the architecture does not degrade. The notes get filed in a notebook for later reference&#xD;
    in case people are curious why the team did something.&#xD;
&lt;/p>&#xD;
&lt;p>&#xD;
    In summary, the following are the range of options for the architecture documentation:&#xD;
&lt;/p>&#xD;
&lt;ol>&#xD;
    &lt;li>&#xD;
        Keep a set of notes that are a historical collection of architecture notes that are not maintained&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Keep a set of notes, plus define a high-level overview of the architecture&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Keep a set of notes, an architectural overview, plus a set of distilled key decisions&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Keep a set of notes, an architectural overview, a set of distilled key decisions and a set of evolutionary models&#xD;
    &lt;/li>&#xD;
    &lt;li>&#xD;
        Keep a set of notes, an architectural overview, a set of distilled key decisions and a set of formal models at&#xD;
        different levels of abstraction&#xD;
    &lt;/li>&#xD;
&lt;/ol>&#xD;
&lt;p>&#xD;
    For each project, it is important to decide which of the above options makes the most sense.&#xD;
&lt;/p></mainDescription>
</org.eclipse.epf.uma:ContentDescription>