Method content elements are:
Defining a method content element involves creating the plug-in that will contain the element (if it does not
already exist), naming the element and briefly describing it. For more information on defining plug-ins, see Guideline: Defining Plugins. For more information on naming, see Guideline: Method Element Naming Conventions. For more information on writing brief
descriptions, see Guideline: Writing Brief Descriptions. Any issues naming an element and briefly
describing it may indicate that the element is not a good element after all.
General Guidelines
The following are some general guidelines when defining method content elements:
-
Reduce the overall number of method content elements (e.g., the number of work products, tasks,
roles). Combine similar elements.
-
Document process-dependent information separate from the method content element
definition. Method content elements should be process independent. Any minor
differences/tweaks to the elements based on where they occur in a particular process or lifecycle 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 Guideline: Defining Processes.
-
Start with the work products. 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.
-
Use guidance to supplement the basics and capture details. 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.
-
Capture the source of the information for the element. This information is important if you
ever need to provide source information for the element for documenting ownership rights.
-
Maintain accurate change histories, as well as making sure your trademarks and copyrights are
accurate. For more information, see Guideline: Maintaining Change Histories and Version Numbers and Guideline: Trademarks and Copyrights.
-
Reuse existing content. 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 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 Guideline: Using Method Content Variability.
-
Use content packages to organize the defined method content elements. When defining method
content elements, you may find that you want to introduce some packages in order to better organize the
elements. For more information, see Guideline: Packaging Method Elements.
The following sections provide method-element-specific guidelines.
Defining work products
There are three types of work products that can be defined:
-
Artifact – provides a description and definition for tangible, non-trivial work product
-
Deliverable – a collection of work products, usually artifacts
-
Outcome – an intangible work product that may be a result or state.
Following are the guidelines for creating each of these work product types.
Defining artifacts
Artifacts are tangible, well-defined work products consumed, produced, or modified by tasks. Artifacts may be composed of other artifacts.
Artifacts are the responsibility of a single role, 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.
Defining deliverables
A deliverable is a work product that provides a description and definition for packaging other work
products, and may be delivered to an internal or external party. Deliverables are used to represent an output from
a process that has value to a client, customer or other stakeholder.
Defining outcomes
An outcome describes an intangible work product 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.
Defining roles
A role defines a set of related skills and competencies. Roles are used by tasks to specify who performs them. Roles may be given responsibilities
for specific work products.
The following are some criteria that affect what roles you define in your method:
-
Organization (what are the roles in the organization that the method supports)
-
Type of project (what roles participate in the projects that the method supports)
-
Style of governance (e.g., different RACI matrices)
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).
The following are some criteria that affect how you assign roles to work products and tasks in your method:
-
Work allocation in the organization and/or on the project that the method supports (who does what)
-
Style of governance (make very precise responsibility assignments; e.g., different RACI matrices -- RACI, RACI-VS,
VARISC, RASCI)
Defining tasks
A task is a description of a unit of work. The performing role
typically transforms the input work products into output work products to achieve a well-defined goal. This
description is complete and independent of when in a process lifecycle the work will actually be performed.
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.
Define tasks so that they are independent of any specific process/lifecycle. 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.
When identifying what tasks are needed, it is important to decide on the granularity of the task. In doing so, the
following should be taken into consideration:
-
A task generally has only one primary output work product. 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 work product.
-
It is recommended that you define a separate task for each state change a work product product goes
through. Since different states need different checklists, have different completion criteria, and
have different execution guidance, it makes sense to have different tasks.
-
When the inputs to a task are different, you probably have two different tasks.
-
When the task is assigned to different roles, you probably want two different tasks.
You identify a 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.
When defining a task, you should also define it's relationships with other method content elements. A
task can have the following relationships with other method content elements:
Defining guidance
Guidance provides additional details to enhance method content. 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. 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.
There are many different types of guidance, all designed for specific purposes. The guidance types are:
-
Checklist – 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.
It is recommended that checklists only be associated with work products and not tasks. If a checklist is
needed for a task, then it can be accessed via the work products associated with the task.
In general, checklists do not require a brief description. However, if there are multiple checklists for a
method element, a brief description is helpful to distinguish between them.
-
Concept – 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.
-
Example – 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.
-
Guideline – 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.
-
Estimation Considerations – 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.
-
Practice – 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.
-
Report – 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.
-
Reusable Asset – 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.
-
Roadmap – 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.
-
Supporting Material – this is a catch-all for assets that do not fit in another type.
-
Template – 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.
-
Term Definition – a definition of a word or phrase that is not in the glossary and that
practitioner need to understand for the method plug-in.
-
Tool Mentor – a description of how to achieve certain goals with a specific tool. Tool mentors
link tasks with tools such as IBM® Rational® Method Composer. They almost completely encapsulate the dependencies
of the content on the tool set, keeping the tasks free from tool details.
-
White Paper – an externally published paper that can be read and understood in isolation of other
content elements and guidance
Guidance should be written with a specific scope in mind. For example:
-
Guidance can be more general, written with regards to a set of elements (e.g., workshops,
collaboration, lifecycle families, etc.)
-
Guidance can be method-element specific (e.g., written regarding a specific work product,
task, role, process) , or
The name of a guidance element should reflect that scope. Specifically, method element-specific guidance should include
the method element name in its name. For example, Guideline: Detailing a Use Case, Template: Use-Case
Template.
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. 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.
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.
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). Method element-specific guidance should be associated with the method element it
describes:
-
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
-
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
-
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)
-
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)
Most guidance should be associated with at least one element. Of course, there are exceptions:
-
Guidance that is about the method, as opposed to being part of the method (e.g., Welcome pages, About pages,
What's new pages, etc.). Such guidance is usually only referred to from navigation views.
-
General guidance (e.g., concepts, white papers) sometimes need to be associated with “general”
elements.
Some possible associations for general concepts are associating to them from standard categories, custom
categories/navigation views, etc.
When defining guidance elements, you must constantly weigh reuse concerns versus complexity:
-
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 then you have many guidance elements, which can be
construed as being more complex).
-
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.
Make the best choice based on your circumstances and let end-user feedback be your guide.
|
