| <?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="-3bATgUtB7jHUdPqdHsZkfQ" |
| name="defining_method_content_elements,_XQqJkCAmEdy1y5bWsXfCCg" guid="-3bATgUtB7jHUdPqdHsZkfQ" |
| changeDate="2008-10-14T06:38:22.984-0700" version="1.0.0"> |
| <mainDescription><p>
 |
| Method content elements are:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <a class="elementLink" href="./../../../core.default.uma_concept.base/guidances/termdefinitions/task_6C1FF051.html"
 |
| guid="_x459ktnmEdmO6L4XMImrsA">task</a>s
 |
| </li>
 |
| <li>
 |
| <a class="elementLink" href="./../../../core.default.uma_concept.base/guidances/termdefinitions/role_37A0C602.html"
 |
| guid="_yUefQNnmEdmO6L4XMImrsA">role</a>s
 |
| </li>
 |
| <li>
 |
| <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_826E4C22.html"
 |
| guid="_H4JXwB_SEdq6CKKKq4D7YA">work product</a>s (<a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/artifact_F635D25.html"
 |
| guid="_x7cUM9nmEdmO6L4XMImrsA">artifact</a>s, <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/outcome_797E7695.html"
 |
| guid="_LNAAcB_iEdqAHrsQ7-jSbw">outcome</a>s and <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/deliverable_BFE1A5A9.html"
 |
| guid="_yFbWoNnmEdmO6L4XMImrsA">deliverable</a>s)
 |
| </li>
 |
| <li>
 |
| <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/guidance_549AC394.html"
 |
| guid="_83ttAB_NEdq6CKKKq4D7YA">guidance</a>
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| Defining a method content element involves creating the plug-in that will contain the element (if&nbsp;it does not
 |
| already exist), naming the element and briefly describing it. For more information on defining plug-ins, see <a
 |
| class="elementLinkWithType" href="./../../../core.mdev.common.base/guidances/guidelines/defining_plugins_CF19789C.html"
 |
| guid="_OIOSQF_zEduYvI5nsNyVYA">Guideline: Defining Plugins</a>.&nbsp;For more information on naming, see <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>. For more information on writing brief
 |
| descriptions, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/writing_brief_descriptions_D01D2F53.html"
 |
| guid="_cJbBkCAhEdy1y5bWsXfCCg">Guideline: Writing Brief Descriptions</a>.&nbsp;Any issues naming an element and briefly
 |
| describing it may indicate that the element is not a&nbsp;good element after all.
 |
| </p>
 |
| <h3>
 |
| General Guidelines
 |
| </h3>
 |
| <p>
 |
| The following are some general guidelines when defining method content elements:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <strong>Reduce the overall number of method content elements</strong> (e.g., the number of work products, tasks,
 |
| roles).&nbsp;Combine similar elements.<br />
 |
| &nbsp;&nbsp; &nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Document process-dependent information separate from the method content element
 |
| definition</strong>.&nbsp;Method content&nbsp;elements should&nbsp;be process independent. Any minor
 |
| differences/tweaks to the elements based on where they occur in&nbsp;a particular process or lifecycle&nbsp;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. For more information on defining processes, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/defining_processes_756EDFA.html"
 |
| guid="_Y_JroEyDEdu4NY1n_hCY0w">Guideline: Defining Processes</a>.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Start with the work products</strong>.&nbsp;When identifying method content elements, its always a good
 |
| idea to start with identifying the work products. Work products are the manifestation of the solution to the
 |
| problem the method addresses. They must be clearly understood at the very beginning of a method authoring project.
 |
| Identifying the work products may appear to consume considerable time but unless they are clearly defined, the
 |
| project will fail. For more information, see the "Defining work products" section below.&nbsp;&nbsp;&nbsp;<br />
 |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Use guidance to supplement</strong> the basics and capture details.&nbsp;Guidance elements can be used to
 |
| supply various kinds of information and assets to method elements so that practitioners are better equipped to
 |
| execute the work.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Capture the source of the information for the element</strong>.&nbsp;This information is important if you
 |
| ever need to provide source information for the element for documenting ownership rights.<br />
 |
| &nbsp;&nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Maintain accurate change histories, as well as making sure your trademarks and copyrights are
 |
| accurate</strong>.&nbsp;For more information, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/maintaining_change_histories_and_version_numbers_B83271.html"
 |
| guid="_k91OkFpBEdutiI3y4Hpy9Q">Guideline: Maintaining Change Histories and Version Numbers</a>&nbsp;and <a
 |
| class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/trademarks_and_copyrights_F14EB70C.html"
 |
| guid="_OxsfkH8MEdu_ipWWZJimvQ">Guideline: Trademarks and Copyrights</a>.<br />
 |
| </li>
 |
| <li>
 |
| <strong>Reuse existing content</strong>. When defining method content elements, it is always a good idea to reuse
 |
| existing content, both content inside the method being developed, as well as content available externally. This is
 |
| especially important in those cases where you are customizing or building on an existing method. Many elements
 |
| may&nbsp;already be defined. It is usually better to start with an existing element than starting from scratch.
 |
| When reusing an existing element, make sure that the content of the element is what you expect. For more
 |
| information on how to leverage existing content and maximize reuse between method content elements, see <a
 |
| class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/using_method_content_variability_DCE37365.html"
 |
| guid="_8YIMYCNQEdycLddDalDmbA">Guideline: Using Method Content Variability</a>.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Use content packages to organize the defined method content elements</strong>.&nbsp;When defining method
 |
| content elements, you may find that you want to introduce some packages in order to better organize the
 |
| elements.&nbsp;For more information, see <a class="elementLinkWithType"
 |
| href="./../../../core.mdev.common.base/guidances/guidelines/packaging_method_elements_E4EC8A32.html"
 |
| guid="_bAjgIIAhEd2RgsZLwhqsAA">Guideline: Packaging Method Elements</a>.
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| The following sections provide method-element-specific guidelines.
 |
| </p>
 |
| <h3>
 |
| Defining work products
 |
| </h3>
 |
| <p>
 |
| There are three types of <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_826E4C22.html"
 |
| guid="_H4JXwB_SEdq6CKKKq4D7YA">work product</a>s that can be defined:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Artifact – provides a description and definition for tangible, non-trivial work product
 |
| </li>
 |
| <li>
 |
| Deliverable – a collection of work products, usually artifacts
 |
| </li>
 |
| <li>
 |
| Outcome – an intangible work product that may be a result or state.
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| Following are the guidelines for creating each of these work product types.<br />
 |
| </p>
 |
| <h4>
 |
| Defining artifacts
 |
| </h4>
 |
| <p>
 |
| <a class="elementLinkWithUserText"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/artifact_F635D25.html"
 |
| guid="_x7cUM9nmEdmO6L4XMImrsA">Artifacts</a> are tangible, well-defined <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_826E4C22.html"
 |
| guid="_H4JXwB_SEdq6CKKKq4D7YA">work product</a>s consumed, produced, or modified by <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/task_6C1FF051.html"
 |
| guid="_x459ktnmEdmO6L4XMImrsA">task</a>s.&nbsp;Artifacts may be composed of other artifacts.
 |
| </p>
 |
| <p>
 |
| Artifacts are the responsibility of a single <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/role_37A0C602.html"
 |
| guid="_yUefQNnmEdmO6L4XMImrsA">role</a>, making responsibility easy to identify and understand, and promoting the idea
 |
| that every piece of information produced in the method requires the appropriate set of skills. Even though one role
 |
| might "own" a specific type of artifact, other roles can still use the artifacts, and perhaps even update them, if the
 |
| role has been given permission to do so.
 |
| </p>
 |
| <h4>
 |
| Defining deliverables
 |
| </h4>
 |
| <p>
 |
| A&nbsp;<a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/deliverable_BFE1A5A9.html"
 |
| guid="_yFbWoNnmEdmO6L4XMImrsA">deliverable</a>&nbsp;is a <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_826E4C22.html"
 |
| guid="_H4JXwB_SEdq6CKKKq4D7YA">work product</a> that provides a description and definition for packaging other work
 |
| products, and may be delivered to an internal or external party.&nbsp;Deliverables are used to represent an output from
 |
| a process that has value to a client, customer or other stakeholder.
 |
| </p>
 |
| <h4>
 |
| Defining outcomes
 |
| </h4>
 |
| <p>
 |
| An <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/outcome_797E7695.html"
 |
| guid="_LNAAcB_iEdqAHrsQ7-jSbw">outcome</a>&nbsp;describes an intangible&nbsp;<a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_826E4C22.html"
 |
| guid="_H4JXwB_SEdq6CKKKq4D7YA">work product</a>&nbsp;that represents a result or state, such as an installed server or
 |
| optimized network. Outcomes may also be used to describe work products that are not formally defined.&nbsp;
 |
| </p>
 |
| <h3 dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| Defining roles
 |
| </h3>
 |
| <p>
 |
| A <a class="elementLink" href="./../../../core.default.uma_concept.base/guidances/termdefinitions/role_37A0C602.html"
 |
| guid="_yUefQNnmEdmO6L4XMImrsA">role</a>&nbsp;defines a set of related skills and competencies. Roles are used by <a
 |
| class="elementLink" href="./../../../core.default.uma_concept.base/guidances/termdefinitions/task_6C1FF051.html"
 |
| guid="_x459ktnmEdmO6L4XMImrsA">task</a>s to specify who performs them.&nbsp; Roles&nbsp;may be given responsibilities
 |
| for specific work products.&nbsp;
 |
| </p>
 |
| <p>
 |
| The following are some criteria that affect what roles you define in your method:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Organization (what are the roles in the organization that the method supports)
 |
| </li>
 |
| <li>
 |
| Type of project (what roles participate in the projects that the method supports)
 |
| </li>
 |
| <li>
 |
| Style of governance (e.g., different RACI matrices)
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| The smaller the number of roles, the better. Define roles to represent distinct skill sets, things a person may choose
 |
| to do for a living, as opposed to something that someone may do on the project at any particular point in time using
 |
| the skills they have with some additional guidance. For example, a person may be an analyst or a designer, but may also
 |
| serve as a reviewer in some circumstances, or may be responsible for implementing a change request. Thus, "analyst" and
 |
| "designer" are good examples of roles, where as "reviewer" and "change request implementer" are not as they perform
 |
| things that anyone can do using their basic skill set (plus some additional guidance like guidelines and checklists).
 |
| </p>
 |
| <p>
 |
| The following are some criteria that affect how you assign roles to work products and tasks in your method:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Work allocation in the organization and/or on the project that the method supports (who does what)
 |
| </li>
 |
| <li>
 |
| Style of governance (make very precise responsibility assignments; e.g., different RACI matrices -- RACI, RACI-VS,
 |
| VARISC, RASCI)<br />
 |
| </li>
 |
| </ul>
 |
| <h3>
 |
| Defining tasks
 |
| </h3>
 |
| <p>
 |
| A <a class="elementLink" href="./../../../core.default.uma_concept.base/guidances/termdefinitions/task_6C1FF051.html"
 |
| guid="_x459ktnmEdmO6L4XMImrsA">task</a>&nbsp;is a description of a unit of work.&nbsp;The performing role
 |
| typically&nbsp;transforms the input <a class="elementLink"
 |
| href="./../../../core.default.uma_concept.base/guidances/termdefinitions/work_product_826E4C22.html"
 |
| guid="_H4JXwB_SEdq6CKKKq4D7YA">work product</a>s into output work products to achieve a well-defined goal.&nbsp;This
 |
| description is complete and independent of when in a process lifecycle the work will actually be performed.
 |
| </p>
 |
| <p>
 |
| Describe tasks in a consistent way, both in terms of naming and in terms of scope/granularity. Try to standardize on a
 |
| key set of verbs and the way those verbs are used in the task names.
 |
| </p>
 |
| <p>
 |
| Define tasks so that they are independent of any specific process/lifecycle.&nbsp;Tasks provide step-by-step
 |
| explanations, describing how specific development goals are achieved independent of the placement of these steps within
 |
| a specific process (e.g., development lifecycle). Processes take these method elements and relate them into
 |
| semi-ordered sequences that are customized to specific types of projects. For example, a software development project
 |
| that develops an application from scratch performs tasks such as "Develop Vision" or "Use Case Design" similar to a
 |
| project that extends an existing software system. However, the two projects will perform the tasks at different points
 |
| in time with a different emphasis, i.e., they perform the steps of these tasks at different points of time and perhaps
 |
| apply individual variations and additions.
 |
| </p>
 |
| <p dir="ltr" style="MARGIN-RIGHT: 0px">
 |
| When identifying what tasks are needed, it is important to decide on the granularity of the task.&nbsp;In doing so, the
 |
| following should be taken into consideration:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <strong>A task generally has only one primary output work product</strong>.&nbsp;However, there are instances where
 |
| more than one work product is worked on simultaneously, so it is possible that you will want to define some tasks
 |
| that do have more than one output&nbsp;work product.<br />
 |
| &nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>It is recommended that you define a separate task for each state change a work product product goes
 |
| through.</strong>&nbsp;Since different states need different checklists, have different completion criteria, and
 |
| have different execution guidance, it makes sense to have different tasks.<br />
 |
| &nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>When the inputs to a task are&nbsp;different</strong>, you probably have two different tasks.<br />
 |
| &nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>When the task is assigned to different roles</strong>, you probably want two different tasks.
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| <span style="FONT-SIZE: 10pt; COLOR: black; FONT-FAMILY: Helv; mso-bidi-font-family: Helv">You identify a&nbsp;task
 |
| when there is a need to transform input work products into outputs through a series of steps performed by one or more
 |
| roles independent of a breakdown structure.</span>
 |
| </p>
 |
| <p>
 |
| When defining a task, you should also define it's relationships with other method content elements.&nbsp;A
 |
| task&nbsp;can have the following relationships with other method content elements:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <strong>Roles:</strong>&nbsp; Two types of roles can be specified:
 |
| </li>
 |
| <li style="LIST-STYLE-TYPE: none">
 |
| <ul>
 |
| <li>
 |
| <div>
 |
| <strong>Primary Performer:</strong>&nbsp; Each task should have a primary performer.&nbsp;This is the
 |
| role this is responsible for ensuring that the task is completed.&nbsp;
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div>
 |
| <strong>Additional Performers:</strong>&nbsp; Additional performers help execute the task.&nbsp;They
 |
| provide information and expertise.<br />
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| </li>
 |
| <li>
 |
| <div>
 |
| <strong>Work Products:</strong>&nbsp; This is where inputs and outputs to the task are
 |
| identified.&nbsp;Specify:
 |
| </div>
 |
| </li>
 |
| <li style="LIST-STYLE-TYPE: none">
 |
| <ul>
 |
| <li>
 |
| <div>
 |
| <strong>Mandatory Inputs:</strong>&nbsp; Mandatory inputs are the work products the task depends upon
 |
| for its successful execution.&nbsp;These are the inputs that the task cannot do without.
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div>
 |
| <strong>Optional Inputs:</strong>&nbsp;&nbsp;Mandatory outputs&nbsp;are the work products that provide
 |
| additional information or context for the task when it is being executed.&nbsp;However, the task does
 |
| not depend on them for successful execution.
 |
| </div>
 |
| </li>
 |
| <li>
 |
| <div>
 |
| <strong>Outputs:</strong>&nbsp;&nbsp;The output work products are those that are produced directly by
 |
| this task.&nbsp;Most tasks will have only one output work product.
 |
| </div>
 |
| </li>
 |
| </ul>
 |
| </li>
 |
| </ul>
 |
| <h3>
 |
| Defining guidance
 |
| </h3>
 |
| <p>
 |
| Guidance provides additional details to enhance method content.&nbsp;In fact, methods are more flexible if the content
 |
| provided in specific method elements is kept as general as possible, with more detail provided as guidance.&nbsp;The
 |
| method can be easily customized by simply adding or removing guidance. This section provides recommendations on how to
 |
| define guidance and how to associate the guidance with other method elements.&nbsp;
 |
| </p>
 |
| <p>
 |
| There are many different types of guidance, all designed for specific purposes.&nbsp;The guidance types are:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <strong>Checklist</strong> – identifies a series of items that need to be completed or verified. Checklists are
 |
| often used in reviews such as walkthroughs or inspections. Checklists may also be a series of questions or a script
 |
| that practitioners may use to lead a discussion with the client’s personnel. This might take the form of a
 |
| questionnaire or interview outline that focuses on the information needed for the work product or deliverable. In
 |
| UMA, a content element has at most one checklist. Checklists are useful in a number of contexts: they help in
 |
| deciding what to do, they help doing it, they help assess the quality of the work, and they help understand how a
 |
| particular work product relates to the rest of the process.<br />
 |
| It is recommended that checklists only be associated with work products and not tasks.&nbsp;If a checklist is
 |
| needed for a task, then it can be accessed via the work products associated with the task.<br />
 |
| In general, checklists do not require a brief description.&nbsp;However, if there are multiple checklists for a
 |
| method element, a brief description is helpful to distinguish between them.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Concept</strong> – outlines key ideas, basic principles and motivations underlying a topic central to the
 |
| method. Concepts normally address more general topics than guidelines and may span several work products, tasks,
 |
| activities, or disciplines. Examples of concepts might be In the context of risk management, performance testing,
 |
| implementation planning.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Example</strong> – a sample instance of a partially or fully formed work product or deliverable. The
 |
| instance may contain live client data (with the client’s express permission to use it) or it may contain fabricated
 |
| data that is representative of the information required for the engagement. However, this example is necessarily
 |
| generic and is only a guide to what might be required in an actual work product or deliverable for a specific
 |
| engagement.<br />
 |
| &nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Guideline</strong> – provides additional details, "how to" information, alternatives, recommendations, or
 |
| rules about the use of a content element. For example, a work product typically has guidelines associated with it
 |
| that provides information on how to develop, evaluate, and use it. Guidelines can provide the context in which a
 |
| work product or other content element exists within a method. A guideline helps practitioners understand how a
 |
| particular content element is used and how it relates to the rest of the process in which it exists. This includes
 |
| formal technique papers for developing work products and deliverables.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Estimation Considerations</strong> – guidance on how to estimate the use in a project of the element with
 |
| which it is associated. The guidance may be textual, a spreadsheet, tool, or take some other form.<br />
 |
| &nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Practice</strong> – a proven way or strategy of doing work to achieve a goal that has a positive impact on
 |
| work product or process quality. Practices are defined orthogonal to methods and processes. They could summarize
 |
| aspects that impact many different parts of a method or specific processes. Examples for practices would be
 |
| "Managing Risks", "Continuously Verifying Quality", "Architecture-centric and Component-based Development", and so
 |
| on.<br />
 |
| &nbsp;&nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Report</strong> – a predefined template of a result that is generated on the basis of one or more work
 |
| products as an output from some form of tool. A report is not an artifact in itself. It is, in most cases, a
 |
| transitory product of a process or monitoring, and a vehicle to communicate certain aspects of the evolving system;
 |
| it is a snapshot description of artifacts that are not documents themselves.<br />
 |
| &nbsp;&nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Reusable Asset</strong> – a type of guidance that references assets that lie outside the method. These
 |
| assets may be too large or volatile to be embedded. These assets may also be third party products or services for
 |
| which usage permission has been granted by the owner.&nbsp;&nbsp;&nbsp;&nbsp;<br />
 |
| &nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Roadmap</strong> – represents important documentation for the activity or process it is related to. Often a
 |
| complex activity such as a process can be much more easily understood by providing a walkthrough with a linear
 |
| thread of a typical instantiation of this activity. In addition to making the process practitioner understand how
 |
| work in the process is being performed, a roadmap provides additional information about how activities and tasks
 |
| relate to each other over time. Roadmaps are also used to show how specific aspects are distributed over a whole
 |
| process providing a kind of filter on the process for this information.<br />
 |
| &nbsp;&nbsp; &nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Supporting Material</strong> – this is a catch-all for assets that do not fit in another type.<br />
 |
| &nbsp;&nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Template</strong> – a version of a work product or deliverable instance that does not contain data so that
 |
| the practitioner may use it to “fill in the blanks”. This is usually a form or set of fields that define the data
 |
| to be collected and may assist in analyzing the data to produce the information for the completed work product or
 |
| deliverable. Taken together the example and the template form a powerful pair for the practitioner. In the first,
 |
| the practitioner sees a completes or partially completed work product while the second offers a convenient means of
 |
| producing the work product as rapidly and as accurately as possible.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Term Definition</strong> – a definition of a word or phrase that is not in the glossary and that
 |
| practitioner need to understand for the method plug-in.<br />
 |
| &nbsp;&nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>Tool Mentor</strong> – a description of how to achieve certain goals with a specific tool. Tool mentors
 |
| link tasks with tools such as IBM&reg; Rational&reg; Method Composer. They almost completely encapsulate the dependencies
 |
| of the content on the tool set, keeping the tasks free from tool details.<br />
 |
| &nbsp;&nbsp;
 |
| </li>
 |
| <li>
 |
| <strong>White Paper</strong> – an externally published paper that can be read and understood in isolation of other
 |
| content elements and guidance
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| Guidance should be written with a specific scope in mind.&nbsp; For example:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Guidance can be more <em><strong>general</strong></em>, written with regards to a set of elements (e.g., workshops,
 |
| collaboration, lifecycle families, etc.)
 |
| </li>
 |
| <li>
 |
| Guidance can be <strong><em>method-element specific</em></strong> (e.g., written regarding a specific work product,
 |
| task, role, process) , or
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| The name of a guidance element should reflect that scope. Specifically, method element-specific guidance should include
 |
| the method element name in its name.&nbsp;For example,&nbsp;Guideline: Detailing a Use Case, Template: Use-Case
 |
| Template.
 |
| </p>
 |
| <p>
 |
| Guidance may be attached to any method element and guidance should be attached to method elements, as needed. However,
 |
| decreasing the number of relationships defined between elements in the method helps to reduce the overall perceived
 |
| complexity of the method.&nbsp;In general, guidance should be associated with the smallest number of elements possible.
 |
| Having "everything associated with everything" is a bad idea as it directly affects the usage of the published web
 |
| site.<br />
 |
| For example, avoid associating the same guidance with work products and tasks that produce the work products as this
 |
| creates unnecessary dependencies since the same content will be linked in via one of the other relationships
 |
| anyway.&nbsp;
 |
| </p>
 |
| <p>
 |
| Guidance should be associated with the element that reflects its scope (i.e., the element where the end-user would be
 |
| expected to look for it).&nbsp; Method element-specific guidance should be associated with the method element it
 |
| describes:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| If the guidance is about notation or representation of a work product (e.g., template, example, checklist) then it
 |
| should be associated with the work product
 |
| </li>
 |
| <li>
 |
| If the guidance describes a specific technique about how to produce the work product then it should be associated
 |
| with a task that produces the work product
 |
| </li>
 |
| <li>
 |
| General guidance should be associated with “general” elements (e.g., slots, standard categories, reference
 |
| workflows, etc.) or possibly just included in custom categories (aka navigation views)
 |
| </li>
 |
| <li>
 |
| Roles are not a common place for associating guidance, unless that guidance is specific to the role (and not to a
 |
| task the role performs or a work product the role is responsible for)
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| Most guidance should be associated with at least one element. Of course, there are exceptions:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| Guidance that is about the method, as opposed to being part of the method (e.g.,&nbsp; Welcome pages, About pages,
 |
| What's new pages, etc.).&nbsp;Such guidance is usually only referred to from navigation views.
 |
| </li>
 |
| <li>
 |
| General guidance (e.g., concepts, white papers) sometimes need to be associated with “general”
 |
| elements.&nbsp;<br />
 |
| Some possible associations for general concepts are associating to them from standard categories, custom
 |
| categories/navigation views, etc.
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| When defining guidance elements, you must constantly weigh reuse concerns versus complexity:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| If you define fine-grained guidance elements, then you can assign the guidance elements to specific method
 |
| elements, which provides just the guidance you need, but&nbsp;then you have many guidance elements, which can be
 |
| construed as being more complex).&nbsp;
 |
| </li>
 |
| <li>
 |
| If you define course-grained guidance elements, then have a smaller number of guidance elements, but then the same
 |
| guidance elements is attached to multiple elements and you have to find what you are looking for by scrolling
 |
| through the course-grained guidance element.
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| Make the best choice based on your circumstances and let end-user feedback be your guide.&nbsp;
 |
| </p></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |