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